Metadata-Version: 2.1
Name: pydatagovgr
Version: 0.1.5
Summary: A Pythonic client for the official https://data.gov.gr API.
Home-page: https://pypi.org/project/pydatagovgr
License: MIT
Keywords: client,pip,govgr,open-data
Author: ilias-ant
Author-email: ilias.antonopoulos@yahoo.gr
Requires-Python: >=3.7,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: Greek
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: requests (>=2.25.1,<2.26.0)
Project-URL: Bug Tracker, https://github.com/ilias-ant/pydatagovgr/issues
Project-URL: Repository, https://github.com/ilias-ant/pydatagovgr
Description-Content-Type: text/markdown

# pydatagovgr

[![PyPI](https://img.shields.io/pypi/v/pydatagovgr)](https://pypi.org/project/pydatagovgr/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydatagovgr)](https://www.python.org/) [![codecov](https://codecov.io/gh/ilias-ant/pydatagovgr/branch/main/graph/badge.svg?token=2H0VB8I8IH)](https://codecov.io/gh/ilias-ant/pydatagovgr) [![PyPI - Wheel](https://img.shields.io/pypi/wheel/pydatagovgr)](https://www.python.org/dev/peps/pep-0427/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/ilias-ant/pydatagovgr/Python%20package)](https://github.com/ilias-ant/pydatagovgr/actions?query=workflow%3A%22Python+package%22)


An unofficial Pythonic client for the official [data.gov.gr](https://data.gov.gr) API. Aims to be an easy, intuitive and out-of-the-box way to:

- find data published by central government, local authorities and public bodies of Greece
- build related products and services.

while being robust, following best-practices and eliminating developer-induced bugs.

The aspiration for this library is to enable users of different backgrounds (academia, industry, students etc.) with 
an interest to programmatically explore and utilize the open data of data.gov.gr, to do so without having to write-debug-maintain trivial code 
or worry about that.

## Install

The recommended installation is via `pip`:

```bash
pip install pydatagovgr
```

## Quick Usage

You must have an account on [data.gov.gr](https://data.gov.gr) to use the API service. In order to register and request
an API token, submit a request in the designated official form [here](https://data.gov.gr/token/). The procedure is very 
simple and takes less than 5 minutes.

```python
from pydatagovgr import DataGovClient


gov_client = DataGovClient(token='xoxb-1234-1243')

# fetch the COVID-19 vaccination data
covid_data = gov_client.query('mdg_emvolio')

# fetch data on Greece's internet traffic
traffic_data = gov_client.query('internet_traffic')

# fetch a list of the forest fires
fire_data = gov_client.query('mcp_forest_fires')
```

## Features

The `pydatagovgr` client supports out-of-the-box all the things you know (and love), such as:

- **authentication**: properly handles the authentication to data.gov.gr - all you have to do is provide a valid token. 
- **persistent session**: making several requests to data.gov.gr reuses the same underlying connection.
- **timeout policy**: the client will stop waiting for a response from data.gov.gr after some time. Defaults to 10 sec.
- **retry policy**: to account for potential server failures of lossy network connections, client automatically retries 
  with an exponential-backoff, to avoid harming the data.gov.gr. Defaults to a maximum of 3 retries.

Also, this library comes with extensive test coverage (100%) of the core functionality. The test suite will constantly
improve towards the v1 version.

## Not-So-Quick Usage

The data.gov.gr API is currently organized into endpoints called **datasets**, each available via the `query` endpoint.

The `pydatagovgr` client provides a corresponding `query` method, through which every available dataset can be obtained.
You can also pass additional arguments to filter the results accordingly. 

```python
from pydatagovgr import DataGovClient


gov_client = DataGovClient(token='xoxb-1234-1243')

# fetch the COVID-19 vaccination data for the 2021
data = gov_client.query('mdg_emvolio', date_from='2021/01/01', date_to='2021/12/31')
```
You can also use Python objects as arguments:

```python
import datetime


data = gov_client.query('mdg_emvolio', 
                        date_from=datetime.date(2021, 1, 1), 
                        date_to=datetime.date(1, 12, 31))
```

Apart from the authentication token, you can also configure the timeout and retry policies of your client. For example: 

```python
from pydatagovgr import DataGovClient


# this client will stop waiting for a response after 7 seconds 
gov_client = DataGovClient(token='xoxb-1234-1243', timeout=7)

# this client will retry at most 3 times, with an exponential-backoff
# (i.e. each retry waits exponentially longer before occurs: 1, 2, 4, 8, 16, 32, 64, ... seconds)
gov_client = DataGovClient(token='xoxb-1234-1243', max_retries=3)

# this client will respect both a timeout policy and a retry policy
gov_client = DataGovClient(token='xoxb-1234-1243', timeout=7, max_retries=3)
```

## How to contribute

If you wish to contribute, [this](CONTRIBUTING.md) is a great place to start!

## License

Distributed under the [MIT License](LICENSE).

## Acknowledgements

All rights are reserved by the official https://data.gov.gr site, its developers, its maintainers and the 
Hellenic Government.

