| Name | fiboa-cli JSON |
| Version |
0.20.3
JSON |
| download |
| home_page | None |
| Summary | CLI tools such as validation and file format conversion for fiboa. |
| upload_time | 2025-09-13 14:37:38 |
| maintainer | None |
| docs_url | None |
| author | Matthias Mohr, Ivor Bosloper |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# fiboa CLI
A command-line interface (CLI) for working with fiboa files.
- [Getting Started](#getting-started)
- [Documentation / Commands](#commands)
- [Development](#development)
## Getting Started
In order to make working with fiboa easier we have developed command-line interface (CLI) tools such as
inspection, validation and file format conversions.
### Installation
#### Using Pixi (Recommended)
This project uses [Pixi](https://pixi.sh/) for dependency management. Install Pixi first, then:
```bash
# Clone the repository and navigate to it
git clone https://github.com/vecorel/cli.git
cd cli
# Install all dependencies
pixi install
# Run the CLI
pixi run fiboa
```
#### Using pip
Alternatively, you can install from PyPI with **Python 3.10** or any later version:
```bash
pip install fiboa-cli
```
### Execute a command
After the installation you should be able to run the following command: `fiboa` (or `pixi run fiboa` if using Pixi)
You should see usage instructions and [available commands](#commands) for the CLI.
fiboa CLI supports various commands to work with the files:
- [fiboa CLI](#fiboa-cli)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Using Pixi (Recommended)](#using-pixi-recommended)
- [Using pip](#using-pip)
- [Execute a command](#execute-a-command)
- [Commands](#commands)
- [Validation](#validation)
- [Create fiboa GeoParquet from GeoJSON](#create-fiboa-geoparquet-from-geojson)
- [Create fiboa GeoJSON from GeoParquet](#create-fiboa-geojson-from-geoparquet)
- [Inspect fiboa GeoParquet file](#inspect-fiboa-geoparquet-file)
- [Merge fiboa GeoParquet files](#merge-fiboa-geoparquet-files)
- [Create JSON Schema from fiboa Schema](#create-json-schema-from-fiboa-schema)
- [Validate a Vecorel Schema](#validate-a-vecorel-schema)
- [Improve a fiboa Parquet file](#improve-a-fiboa-parquet-file)
- [Update an extension template with new names](#update-an-extension-template-with-new-names)
- [Converter for existing datasets](#converter-for-existing-datasets)
- [Development](#development)
- [Implement a converter](#implement-a-converter)
## Commands
### Validation
To validate a Vecorel GeoParquet or GeoJSON file, you can for example run:
- GeoJSON: `fiboa validate example.json --collection collection.json`
- GeoParquet: `fiboa validate example.parquet --data`
Check `fiboa validate --help` for more details.
The validator also supports remote files.
- `http://` or `https://`: no further configuration is needed.
- `s3://`: With Pixi, run `pixi install -e s3` or with pip, run `pip install fiboa-cli[s3]` and you may need to set environment variables.
Refer to the [s3fs credentials documentation](https://s3fs.readthedocs.io/en/latest/#credentials) for how to define credentials.
- `gs://`: With Pixi, run `pixi install -e gcs` or with pip, run `pip install fiboa-cli[gcs]`.
By default, `gcsfs` will attempt to use your default gcloud credentials or, attempt to get credentials from the google metadata service, or fall back to anonymous access.
### Create fiboa GeoParquet from GeoJSON
To create a fiboa-compliant GeoParquet for a fiboa-compliant set of GeoJSON files containing Features or FeatureCollections,
you can for example run:
- `fiboa create-geoparquet geojson/example.json -o example.parquet -c geojson/collection.json`
Check `fiboa create-geoparquet --help` for more details.
### Create fiboa GeoJSON from GeoParquet
To create one or multiple fiboa-compliant GeoJSON file(s) for a fiboa-compliant GeoParquet file,
you can for example run:
- GeoJSON FeatureCollection:
`fiboa create-geojson example.parquet -o dest-folder`
- GeoJSON Features (with indentation and max. 100 features):
`fiboa create-geojson example.parquet -o dest-folder -n 100 -i 2 -f`
`fiboa create-geojson example.parquet -o dest-folder -n 100 -i 2 -f`
Check `fiboa create-geojson --help` for more details.
### Inspect fiboa GeoParquet file
To look into a fiboa GeoParquet file to get a rough understanding of the content, the following can be executed:
- `fiboa describe example.parquet`
Check `fiboa describe --help` for more details.
### Merge fiboa GeoParquet files
Merges multiple fiboa datasets to a combined fiboa dataset:
- `fiboa merge ec_ee.parquet ec_lv.parquet -o merged.parquet -e https://fiboa.org/hcat-extension/v0.1.0/schema.yaml -i ec:hcat_name -i ec:hcat_code -i ec:translated_name`
Check `fiboa merge --help` for more details.
### Create JSON Schema from fiboa Schema
To create a JSON Schema for a fiboa Schema YAML file, you can for example run:
- `fiboa jsonschema example.json --id=https://vecorel.org/specification/v0.3.0/geojson/schema.json -o schema.json`
Check `fiboa jsonschema --help` for more details.
### Validate a Vecorel Schema
To validate a Vecorel Schema YAML file, you can for example run:
- `fiboa validate-schema schema/schema.yaml`
Check `fiboa validate-schema --help` for more details.
### Improve a fiboa Parquet file
Various "improvements" can be applied to a fiboa GeoParquet file.
The commands allows to
- change the CRS (`--crs`)
- change the GeoParquet version (`-gp1`) and compression (`-pc`)
- add/fill missing perimeter/area values (`-sz`)
- fix invalid geometries (`-g`)
- rename columns (`-r`)
Example:
- `fiboa improve file.parquet -o file2.parquet -g -sz -r old=new -pc zstd`
Check `fiboa improve --help` for more details.
### Update an extension template with new names
Once you've created and git cloned a new extension, you can use the CLI
to update all template placeholders with proper names.
For example, if your extension is meant to have
- the title "Administrative Division Extension",
- the prefix `admin` (e.g. field `admin:country_code` or `admin:subdivision_code`),
- is hosted at `https://github.io/vecorel/administrative-division-extension`
(organization: `vecorel`, repository `/administrative-division-extension`),
- and you run Vecorel in the folder of the extension.
Then the following command could be used:
- `fiboa rename-extension . -t "Administrative Division" -p admin -s administrative-division-extension -o vecorel`
Check `fiboa rename-extension --help` for more details.
### Converter for existing datasets
The CLI ships various converters for existing datasets.
To get a list of available converters/datasets with title, license, etc. run:
- `fiboa converters`
Use any of the IDs from the list to convert an existing dataset to fiboa:
- `fiboa convert de_nrw`
See [Implement a converter](#implement-a-converter) for details about how to
## Development
This project uses [Pixi](https://pixi.sh/) for dependency management and development workflows.
```bash
# Install all dependencies including development tools
pixi install -e dev
# Install the package in editable mode
pixi run install-dev
# Run tests
pixi run test
# Format and lint code
pixi run format
pixi run lint
# Run all checks (lint, format, test)
pixi run check
# Install and run pre-commit
pixi run pre-commit-install
pixi run pre-commit-run
```
### Implement a converter
The following high-level description gives an idea how to implement a converter in fiboa CLI:
1. Create a new file in `fiboa_cli/datasets` based on the `template.py`
2. Fill in the required variables / test it / run it
3. Add missing dependencies into the appropriate feature group in `pixi.toml` (or `setup.py` for pip users)
4. Add the converter to the list above
5. Create a PR to submit your converter for review
Raw data
{
"_id": null,
"home_page": null,
"name": "fiboa-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Matthias Mohr, Ivor Bosloper",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1c/e3/19cde55852a8a818309ad7f5d4a7361cd43657d47e6a596636559f6f66ac/fiboa_cli-0.20.3.tar.gz",
"platform": null,
"description": "# fiboa CLI\n\nA command-line interface (CLI) for working with fiboa files.\n\n- [Getting Started](#getting-started)\n- [Documentation / Commands](#commands)\n- [Development](#development)\n\n## Getting Started\n\nIn order to make working with fiboa easier we have developed command-line interface (CLI) tools such as\ninspection, validation and file format conversions.\n\n### Installation\n\n#### Using Pixi (Recommended)\n\nThis project uses [Pixi](https://pixi.sh/) for dependency management. Install Pixi first, then:\n\n```bash\n# Clone the repository and navigate to it\ngit clone https://github.com/vecorel/cli.git\ncd cli\n\n# Install all dependencies\npixi install\n\n# Run the CLI\npixi run fiboa\n```\n\n#### Using pip\n\nAlternatively, you can install from PyPI with **Python 3.10** or any later version:\n\n```bash\npip install fiboa-cli\n```\n\n### Execute a command\n\nAfter the installation you should be able to run the following command: `fiboa` (or `pixi run fiboa` if using Pixi)\n\nYou should see usage instructions and [available commands](#commands) for the CLI.\n\nfiboa CLI supports various commands to work with the files:\n\n- [fiboa CLI](#fiboa-cli)\n - [Getting Started](#getting-started)\n - [Installation](#installation)\n - [Using Pixi (Recommended)](#using-pixi-recommended)\n - [Using pip](#using-pip)\n - [Execute a command](#execute-a-command)\n - [Commands](#commands)\n - [Validation](#validation)\n - [Create fiboa GeoParquet from GeoJSON](#create-fiboa-geoparquet-from-geojson)\n - [Create fiboa GeoJSON from GeoParquet](#create-fiboa-geojson-from-geoparquet)\n - [Inspect fiboa GeoParquet file](#inspect-fiboa-geoparquet-file)\n - [Merge fiboa GeoParquet files](#merge-fiboa-geoparquet-files)\n - [Create JSON Schema from fiboa Schema](#create-json-schema-from-fiboa-schema)\n - [Validate a Vecorel Schema](#validate-a-vecorel-schema)\n - [Improve a fiboa Parquet file](#improve-a-fiboa-parquet-file)\n - [Update an extension template with new names](#update-an-extension-template-with-new-names)\n - [Converter for existing datasets](#converter-for-existing-datasets)\n - [Development](#development)\n - [Implement a converter](#implement-a-converter)\n\n## Commands\n\n### Validation\n\nTo validate a Vecorel GeoParquet or GeoJSON file, you can for example run:\n\n- GeoJSON: `fiboa validate example.json --collection collection.json`\n- GeoParquet: `fiboa validate example.parquet --data`\n\nCheck `fiboa validate --help` for more details.\n\nThe validator also supports remote files.\n\n- `http://` or `https://`: no further configuration is needed.\n- `s3://`: With Pixi, run `pixi install -e s3` or with pip, run `pip install fiboa-cli[s3]` and you may need to set environment variables.\n Refer to the [s3fs credentials documentation](https://s3fs.readthedocs.io/en/latest/#credentials) for how to define credentials.\n- `gs://`: With Pixi, run `pixi install -e gcs` or with pip, run `pip install fiboa-cli[gcs]`.\n By default, `gcsfs` will attempt to use your default gcloud credentials or, attempt to get credentials from the google metadata service, or fall back to anonymous access.\n\n### Create fiboa GeoParquet from GeoJSON\n\nTo create a fiboa-compliant GeoParquet for a fiboa-compliant set of GeoJSON files containing Features or FeatureCollections,\nyou can for example run:\n\n- `fiboa create-geoparquet geojson/example.json -o example.parquet -c geojson/collection.json`\n\nCheck `fiboa create-geoparquet --help` for more details.\n\n### Create fiboa GeoJSON from GeoParquet\n\nTo create one or multiple fiboa-compliant GeoJSON file(s) for a fiboa-compliant GeoParquet file,\nyou can for example run:\n\n- GeoJSON FeatureCollection:\n `fiboa create-geojson example.parquet -o dest-folder`\n- GeoJSON Features (with indentation and max. 100 features):\n `fiboa create-geojson example.parquet -o dest-folder -n 100 -i 2 -f`\n\n `fiboa create-geojson example.parquet -o dest-folder -n 100 -i 2 -f`\n\nCheck `fiboa create-geojson --help` for more details.\n\n### Inspect fiboa GeoParquet file\n\nTo look into a fiboa GeoParquet file to get a rough understanding of the content, the following can be executed:\n\n- `fiboa describe example.parquet`\n\nCheck `fiboa describe --help` for more details.\n\n### Merge fiboa GeoParquet files\n\nMerges multiple fiboa datasets to a combined fiboa dataset:\n\n- `fiboa merge ec_ee.parquet ec_lv.parquet -o merged.parquet -e https://fiboa.org/hcat-extension/v0.1.0/schema.yaml -i ec:hcat_name -i ec:hcat_code -i ec:translated_name`\n\nCheck `fiboa merge --help` for more details.\n\n### Create JSON Schema from fiboa Schema\n\nTo create a JSON Schema for a fiboa Schema YAML file, you can for example run:\n\n- `fiboa jsonschema example.json --id=https://vecorel.org/specification/v0.3.0/geojson/schema.json -o schema.json`\n\nCheck `fiboa jsonschema --help` for more details.\n\n### Validate a Vecorel Schema\n\nTo validate a Vecorel Schema YAML file, you can for example run:\n\n- `fiboa validate-schema schema/schema.yaml`\n\nCheck `fiboa validate-schema --help` for more details.\n\n### Improve a fiboa Parquet file\n\nVarious \"improvements\" can be applied to a fiboa GeoParquet file.\nThe commands allows to\n\n- change the CRS (`--crs`)\n- change the GeoParquet version (`-gp1`) and compression (`-pc`)\n- add/fill missing perimeter/area values (`-sz`)\n- fix invalid geometries (`-g`)\n- rename columns (`-r`)\n\nExample:\n\n- `fiboa improve file.parquet -o file2.parquet -g -sz -r old=new -pc zstd`\n\nCheck `fiboa improve --help` for more details.\n\n### Update an extension template with new names\n\nOnce you've created and git cloned a new extension, you can use the CLI\nto update all template placeholders with proper names.\n\nFor example, if your extension is meant to have\n\n- the title \"Administrative Division Extension\",\n- the prefix `admin` (e.g. field `admin:country_code` or `admin:subdivision_code`),\n- is hosted at `https://github.io/vecorel/administrative-division-extension`\n (organization: `vecorel`, repository `/administrative-division-extension`),\n- and you run Vecorel in the folder of the extension.\n\nThen the following command could be used:\n\n- `fiboa rename-extension . -t \"Administrative Division\" -p admin -s administrative-division-extension -o vecorel`\n\nCheck `fiboa rename-extension --help` for more details.\n\n### Converter for existing datasets\n\nThe CLI ships various converters for existing datasets.\n\nTo get a list of available converters/datasets with title, license, etc. run:\n\n- `fiboa converters`\n\nUse any of the IDs from the list to convert an existing dataset to fiboa:\n\n- `fiboa convert de_nrw`\n\nSee [Implement a converter](#implement-a-converter) for details about how to\n\n## Development\n\nThis project uses [Pixi](https://pixi.sh/) for dependency management and development workflows.\n\n```bash\n# Install all dependencies including development tools\npixi install -e dev\n\n# Install the package in editable mode\npixi run install-dev\n\n# Run tests\npixi run test\n\n# Format and lint code\npixi run format\npixi run lint\n\n# Run all checks (lint, format, test)\npixi run check\n\n# Install and run pre-commit\npixi run pre-commit-install\npixi run pre-commit-run\n```\n\n### Implement a converter\n\nThe following high-level description gives an idea how to implement a converter in fiboa CLI:\n\n1. Create a new file in `fiboa_cli/datasets` based on the `template.py`\n2. Fill in the required variables / test it / run it\n3. Add missing dependencies into the appropriate feature group in `pixi.toml` (or `setup.py` for pip users)\n4. Add the converter to the list above\n5. Create a PR to submit your converter for review\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI tools such as validation and file format conversion for fiboa.",
"version": "0.20.3",
"project_urls": {
"Bug Reports": "https://github.com/fiboa/cli/issues",
"Homepage": "https://github.com/fiboa/cli",
"Source": "https://github.com/fiboa/cli"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9a0b63ecbcd4e270d71692544503fc4ab5408a95af403942221d4a76cf61d386",
"md5": "de4b4a2b6ef15fee14d0d9c2158dc3ba",
"sha256": "d051a434d742c03d83b676dfaed57a3baa82f763b58481c16d48d9bcd9c31162"
},
"downloads": -1,
"filename": "fiboa_cli-0.20.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de4b4a2b6ef15fee14d0d9c2158dc3ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 101274,
"upload_time": "2025-09-13T14:37:37",
"upload_time_iso_8601": "2025-09-13T14:37:37.638680Z",
"url": "https://files.pythonhosted.org/packages/9a/0b/63ecbcd4e270d71692544503fc4ab5408a95af403942221d4a76cf61d386/fiboa_cli-0.20.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1ce319cde55852a8a818309ad7f5d4a7361cd43657d47e6a596636559f6f66ac",
"md5": "404ce4c4099004196a1bb76938caf7a6",
"sha256": "f2a745959143680cca39d78b0c456efd8db672452745f257565ed5841b6f00fe"
},
"downloads": -1,
"filename": "fiboa_cli-0.20.3.tar.gz",
"has_sig": false,
"md5_digest": "404ce4c4099004196a1bb76938caf7a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 67468,
"upload_time": "2025-09-13T14:37:38",
"upload_time_iso_8601": "2025-09-13T14:37:38.870020Z",
"url": "https://files.pythonhosted.org/packages/1c/e3/19cde55852a8a818309ad7f5d4a7361cd43657d47e6a596636559f6f66ac/fiboa_cli-0.20.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 14:37:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fiboa",
"github_project": "cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fiboa-cli"
}
