Metadata-Version: 2.4
Name: diariopy
Version: 0.1.1
Summary: Python interface to the Diário de Obras (diariodeobras.net) API
Project-URL: Homepage, https://github.com/StrategicProjects/diariopy
Project-URL: Repository, https://github.com/StrategicProjects/diariopy
Project-URL: Issues, https://github.com/StrategicProjects/diariopy/issues
Author-email: André Leite <leite@castlab.org>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>, Marcos Wasiliew <marcos.wasilew@gmail.com>, Carlos Amorim <carlos.agaf@ufpe.br>, Felipe Ferreira <felipe.ferreira@semobi.pe.gov.br>, Roger Azevedo <roger.azevedo@tpfe.com.br>
License-Expression: MIT
License-File: LICENSE
Keywords: api,client,construction,diariodeobras,obras
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: keyring>=23.0
Requires-Dist: requests>=2.25
Provides-Extra: docs
Requires-Dist: black>=24.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: responses>=0.23; extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/diariopy-hex.svg" alt="diariopy hex logo" width="200">
</p>

# diariopy

[![CI](https://github.com/StrategicProjects/diariopy/actions/workflows/ci.yml/badge.svg)](https://github.com/StrategicProjects/diariopy/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/diariopy.svg)](https://pypi.org/project/diariopy/)
[![Python](https://img.shields.io/pypi/pyversions/diariopy.svg)](https://pypi.org/project/diariopy/)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://strategicprojects.github.io/diariopy/)

**diariopy** is a Python interface to the [diariodeobras.net](https://diariodeobras.net)
("Diário de Obras") platform — the Python counterpart of the R package
[`diario`](https://github.com/StrategicProjects/diario). It securely stores an API
token and wraps authenticated requests to retrieve projects, tasks, reports, and more.

> 📦 **Using R?** See the sibling package [**diario**](https://github.com/StrategicProjects/diario)
> ([CRAN](https://cran.r-project.org/package=diario) · [docs](https://strategicprojects.github.io/diario/)).

> **Disclaimer.** This package is a wrapper for the API provided by the **Diário de
> Obras** platform, which owns the data. Function and argument names are in English,
> but because the source API is in Portuguese, **response keys and some data values
> are returned in Portuguese**. Access requires a valid authentication token issued
> by the platform.

## Installation

```bash
pip install diariopy
```

## Getting started

```python
import diariopy

# 1. Store your API token securely (uses the system keyring)
diariopy.store_token("YOUR_API_TOKEN_HERE")

# 2. Confirm it was stored
diariopy.retrieve_token()

# 3. Make authenticated requests
company = diariopy.get_company()
projects = diariopy.get_projects()
```

## Usage

```python
project_id = "6717f864d163f517ae06e242"

diariopy.get_entities()                      # registered entities (cadastros)
diariopy.get_project_details(project_id)     # one project
diariopy.get_task_list(project_id)           # schedule items (cronograma)
diariopy.get_task_details(project_id, task_id)
diariopy.get_reports(project_id, limit=10, order="asc")
diariopy.get_report_details(project_id, report_id)
```

All getters return parsed JSON (Python ``dict``/``list``). Request failures raise
``diariopy.DiarioError``; invalid arguments raise ``ValueError``.

### Configuration

- **Base URL** — override with the ``DIARIO_BASE_URL`` environment variable (useful
  for staging or testing).
- **Logging** — the package logs through the ``diariopy`` logger and does not print.

## Development

```bash
uv sync --extra test      # or: pip install -e ".[test]"
uv run pytest             # tests mock the network; no token required
uv build                  # build sdist + wheel
```

## Citation

If you use **diariopy** in your work, please cite it. Citation metadata lives in
[`CITATION.cff`](CITATION.cff); GitHub renders a ready-to-use citation from it via
the "Cite this repository" button.

## License

MIT — see [LICENSE](LICENSE).
