Skip to content

Commit 86a1fad

Browse files
temponttempont
committed
fix: docstrings and coding issues
1 parent 1129085 commit 86a1fad

76 files changed

Lines changed: 4205 additions & 468 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 17 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,34 +5,31 @@ on:
55
branches: [main]
66
pull_request:
77

8-
concurrency:
9-
group: ci-${{ github.workflow }}-${{ github.ref }}
10-
cancel-in-progress: true
8+
permissions:
9+
contents: read
1110

1211
jobs:
13-
check:
12+
quality:
13+
name: Quality Checks
1414
runs-on: ubuntu-latest
15+
strategy:
16+
matrix:
17+
python-version: ["3.12", "3.13"]
1518
steps:
16-
- name: Checkout
17-
uses: actions/checkout@v4
18-
19+
- uses: actions/checkout@v4
1920
- name: Install uv
20-
uses: astral-sh/setup-uv@v5
21+
uses: astral-sh/setup-uv@v3
2122
with:
22-
python-version: "3.14"
2323
enable-cache: true
24-
24+
- name: Set up Python ${{ matrix.python-version }}
25+
run: uv python install ${{ matrix.python-version }}
2526
- name: Install dependencies
26-
run: uv sync --all-groups
27-
28-
- name: Ruff lint
27+
run: uv sync --all-groups --python ${{ matrix.python-version }}
28+
- name: Ruff check
2929
run: uv run ruff check .
30-
31-
- name: Ruff format
30+
- name: Ruff format check
3231
run: uv run ruff format --check .
33-
34-
- name: Type check
32+
- name: Basedpyright
3533
run: uv run basedpyright
36-
37-
- name: Tests
38-
run: uv run pytest
34+
- name: Pytest
35+
run: uv run python -m pytest

‎.github/workflows/docs.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
permissions:
8+
contents: read
9+
pages: write
10+
id-token: write
11+
12+
concurrency:
13+
group: "pages"
14+
cancel-in-progress: true
15+
16+
jobs:
17+
build-docs:
18+
name: Build documentation
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
- name: Install uv
23+
uses: astral-sh/setup-uv@v3
24+
with:
25+
enable-cache: true
26+
- name: Set up Python
27+
run: uv python install 3.12
28+
- name: Install dependencies
29+
run: uv sync --extra docs
30+
- name: Build docs
31+
run: uv run mkdocs build --strict
32+
- name: Upload artifact
33+
uses: actions/upload-pages-artifact@v3
34+
with:
35+
path: site/
36+
37+
deploy-docs:
38+
name: Deploy to GitHub Pages
39+
needs: build-docs
40+
runs-on: ubuntu-latest
41+
environment:
42+
name: github-pages
43+
url: ${{ steps.deployment.outputs.page_url }}
44+
steps:
45+
- name: Deploy to GitHub Pages
46+
id: deployment
47+
uses: actions/deploy-pages@v4

‎.github/workflows/publish.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
8+
permissions:
9+
contents: read
10+
id-token: write # Required for trusted publishing
11+
12+
jobs:
13+
build:
14+
name: Build distribution
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- name: Install uv
19+
uses: astral-sh/setup-uv@v3
20+
with:
21+
enable-cache: true
22+
- name: Set up Python
23+
run: uv python install 3.12
24+
- name: Install dependencies
25+
run: uv sync --all-groups
26+
- name: Run quality checks
27+
run: make check
28+
- name: Build package
29+
run: uv build
30+
- name: Upload distributions
31+
uses: actions/upload-artifact@v4
32+
with:
33+
name: dist
34+
path: dist/
35+
36+
publish:
37+
name: Publish to PyPI
38+
needs: build
39+
runs-on: ubuntu-latest
40+
environment: pypi
41+
permissions:
42+
id-token: write # Trusted publishing (OIDC)
43+
steps:
44+
- name: Download distributions
45+
uses: actions/download-artifact@v4
46+
with:
47+
name: dist
48+
path: dist/
49+
- name: Publish to PyPI
50+
uses: pypa/gh-action-pypi-publish@release/v1

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,10 +63,10 @@ docs/_references/
6363
data
6464
.cursor/
6565
.codegraph/
66-
AGENTS.md
6766
scripts/dev_test*
6867
examples/dev/
6968
.opencode
7069
site
7170
typings/
7271
test-results/
72+
examples/.auth/

‎AGENTS.md‎

Lines changed: 250 additions & 0 deletions
Large diffs are not rendered by default.

‎CHANGELOG.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Breaking Changes
11+
12+
- `VendedoresResource.list()` parameter names changed from Portuguese to English
13+
- 408 status code reclassified from `BlingValidationError` to `BlingTransportError`
14+
- `NotificacoesResource.alterar()` renamed to `confirmar_leitura()` (`alterar()` is now a compatibility alias)
15+
- `HomologationResource.set_status()` renamed to `update_status()` (`set_status()` is now a compatibility alias)
16+
- `to_json_object()` no longer drops explicitly-set default values
17+
18+
## [0.1.0] - 2026-06-23
19+
20+
### Added
21+
22+
- Initial public release of the Bling ERP API SDK
23+
- 40+ resource modules covering products, orders, invoices, contacts, logistics, and more
24+
- OAuth2 authentication via bling-jwt-auth
25+
- Sync and async transport with rate limiting and 429 retry
26+
- Pydantic v2 typed models with snake_case public API
27+
- pt-BR canonical methods with English compatibility aliases
28+
- OpenAPI contract generation and validation
29+
- Comprehensive test suite (500+ tests)

‎CONTRIBUTING.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Contributing
2+
3+
Thank you for considering contributing to the Bling ERP API SDK!
4+
5+
## Development Setup
6+
7+
1. Clone the repository:
8+
9+
```bash
10+
git clone https://github.com/tempont/bling-erp-api-python.git
11+
cd bling-erp-api-python
12+
```
13+
14+
2. Install dependencies with `uv`:
15+
16+
```bash
17+
uv sync --all-groups
18+
```
19+
20+
3. Run the full check suite to verify everything works:
21+
22+
```bash
23+
make check
24+
```
25+
26+
## Code Style
27+
28+
This project uses:
29+
30+
- **Ruff** for linting and formatting (see `pyproject.toml` for configuration)
31+
- **basedpyright** for type checking (strict mode)
32+
33+
Run linting and formatting before committing:
34+
35+
```bash
36+
uv run ruff check . && uv run ruff format --check .
37+
```
38+
39+
Or let pre-commit handle it:
40+
41+
```bash
42+
uv run pre-commit run --all-files
43+
```
44+
45+
## Code Generation
46+
47+
Some models and contracts are generated from the Bling OpenAPI specification:
48+
49+
```bash
50+
make codegen
51+
```
52+
53+
This runs the scripts under `scripts/`:
54+
55+
- `generate_openapi_contracts.py` — generates resource contracts
56+
- `generate_models.py` — generates Pydantic models
57+
58+
Generated files live in:
59+
60+
- `src/bling_erp_api/contracts/generated/`
61+
- `src/bling_erp_api/models/generated/`
62+
- `docs/resources/`
63+
64+
## Testing
65+
66+
Run the test suite:
67+
68+
```bash
69+
uv run python -m pytest
70+
```
71+
72+
Or with coverage:
73+
74+
```bash
75+
uv run python -m pytest --cov=bling_erp_api
76+
```
77+
78+
**Important**: Tests must not make real API calls unless explicitly gated behind environment variables. Use `pytest-httpx` for HTTP mocking.
79+
80+
## Adding a New Endpoint
81+
82+
Follow the checklist in `AGENTS.md` (located in the repository root) for adding new endpoints. The key steps are:
83+
84+
1. Find the operation in `specs/bling-openapi-reference.json`
85+
2. Add resource/action mappings to `scripts/generate_openapi_contracts.py`
86+
3. Run contract generation
87+
4. Create or update the resource class in `src/bling_erp_api/resources/`
88+
5. Add the resource namespace to the client
89+
6. Add tests (contract tests, resource mapping tests, model tests)
90+
91+
## Pull Request Workflow
92+
93+
1. Fork the repository
94+
2. Create a feature branch (`git checkout -b feat/my-feature`)
95+
3. Make your changes
96+
4. Run `make check` to verify
97+
5. Commit with a clear message
98+
6. Push and open a pull request
99+
100+
## Project Conventions
101+
102+
For deep conventions on naming, docstrings, model structure, and resource implementation, see the `AGENTS.md` file in the repository root. It documents the complete project design decisions and per-endpoint checklist.
103+
104+
## License
105+
106+
By contributing, you agree that your contributions will be licensed under the MIT License.

0 commit comments

Comments
 (0)