Metadata-Version: 2.4
Name: ods_utils_py
Version: 0.2.6
Summary: A python wrapper library for the ODS Automation API
Home-page: https://github.com/opendatasoft/ods-utils-py/
Author: Renato FARRUGGIO
Author-email: renato.farruggio@bs.ch
License: MIT License
        
        Copyright (c) 2024 Renato FARRUGGIO
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2025.11.12
Requires-Dist: charset-normalizer>=3.4.4
Requires-Dist: colorama>=0.4.6
Requires-Dist: idna>=3.11
Requires-Dist: iniconfig>=2.3.0
Requires-Dist: packaging>=25.0
Requires-Dist: pluggy>=1.6.0
Requires-Dist: pytest>=9.0.2
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: requests>=2.32.5
Requires-Dist: setuptools>=80.9.0
Requires-Dist: six>=1.17.0
Requires-Dist: tzdata>=2025.2
Requires-Dist: urllib3>=2.6.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ods-utils-py
With `ods-utils-py`, the Automation API from Opendatasoft can be accessed directly from Python. A valid API key is required ([Create an API key](#set-up-api-key)). [The source code is publicly available on GitHub](https://github.com/opendatabs/ods-utils-py).

## Installation

Installation via `pip`:

```bash
pip install ods-utils-py
```

---

## Requirements

- **Python Version:** 3.11 or higher
- **API Key:** A valid API key from Opendatasoft

---

## Getting Started

### Set up API Key

To use `ods-utils-py`, a valid API key from Opendatasoft is required.

[For OGD Basel, the API key can be created here](https://data.bs.ch/account/api-keys/).

For key creation on other platforms, click on the username button in the top right corner to open account settings. Under API Keys, custom keys with the appropriate permissions can be created.

The name should describe its purpose, for example, `"ods_utils_py - <Initial Key Name>"`

The API key requires the following 4 permissions:
- Browse all datasets
- Create new datasets
- Edit all datasets
- Publish own datasets

The API key is then required as an environment variable.

### Set up Environment Variables
Next, the environment variables must be defined. For this, add a `.env` file in the root directory with the following content. If a `.env` already exists, just append the following content:

```.env
ODS_API_KEY=your_ods_api_key

ODS_DOMAIN=data.bs.ch
ODS_API_TYPE=automation/v1.0
```

**Important:** Make sure to add `**/.env` to your .gitignore to not upload the credentials to the internet!  

## Usage

Here's a simple example to retrieve the number of datasets:

```python
import ods_utils_py as ods_utils

num_datasets = ods_utils.get_number_of_datasets()
print(f"We currently have {num_datasets} datasets.")
```

A list of all currently implemented functions can be found on [GitHub](https://github.com/opendatabs/ods-utils-py/tree/main/src/ods_utils_py).

If a desired function does not exist, it can be implemented via _requests_utils:

```python
import ods_utils_py as ods_utils

response = ods_utils._requests_utils.requests_get("https://www.example.com")
print(response.text)
```

*Note:* Most of these functions should eventually be integrated into `ods_utils_py` if they use the Automation API.

---

## Further Links
The complete documentation of the Automation API 1.0 can be found [here](https://help.opendatasoft.com/apis/ods-automation-v1/).

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file in the repository for the full license text.

---
