tiny-erp-py 0.1.0__tar.gz

tiny_erp_py-0.1.0/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install:*)",
+      "Bash(python -m pytest tests/ -v)",
+      "Bash(python -m pytest tests/test_exceptions.py -v)",
+      "Bash(python -m pytest tests/test_rate_limiter.py -v)",
+      "Bash(python -m pytest tests/test_models.py -v)",
+      "Bash(python -m pytest tests/test_http.py -v)",
+      "Bash(python -m pytest tests/test_resources.py -v)",
+      "Bash(python -m pytest tests/test_client.py -v)",
+      "Bash(pip show:*)",
+      "Bash(curl -s https://pypi.org/pypi/tiny-py/json)",
+      "Bash(python -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(''''EXISTS:'''', d[''''info''''][''''version'''']\\)\")",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://pypi.org/pypi/tiny-py/json)",
+      "Bash(pytest tests/ -q)",
+      "Bash(python -m build)",
+      "Bash(python -m twine check dist/*)",
+      "Bash(TWINE_USERNAME=Joaoaalves TWINE_PASSWORD='mz.@T6?hMJ46!~.' python -m twine upload dist/*)",
+      "Bash(TWINE_USERNAME=__token__ TWINE_PASSWORD='pypi-AgEIcHlwaS5vcmcCJGFlMDcwODgwLWVmODctNDk3MC1hYzIxLTY0ODBhMWVmNGU4ZQACKlszLCJmNjVmMTJiYi00MmZkLTQ4OTYtODNlMi0zNjM4NmJkZjVkNTkiXQAABiCUVbejFSVH8tsk5GtzvitQvNVHs2dbHmXxZRscrZ3Niw' python -m twine upload dist/*)",
+      "Bash(TWINE_USERNAME=__token__ TWINE_PASSWORD='pypi-AgEIcHlwaS5vcmcCJGFlMDcwODgwLWVmODctNDk3MC1hYzIxLTY0ODBhMWVmNGU4ZQACKlszLCJmNjVmMTJiYi00MmZkLTQ4OTYtODNlMi0zNjM4NmJkZjVkNTkiXQAABiCUVbejFSVH8tsk5GtzvitQvNVHs2dbHmXxZRscrZ3Niw' python -m twine upload dist/* --verbose)",
+      "Bash(rm -rf dist/)",
+      "Bash(python -m build -q)"
+    ]
+  }
+}

tiny_erp_py-0.1.0/.gitignore

@@ -0,0 +1,179 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python
+# Edit at https://www.toptal.com/developers/gitignore?templates=python
+
+# IF SOMEONE USES AI
+*/CLAUDE.md
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# End of https://www.toptal.com/developers/gitignore/api/python

tiny_erp_py-0.1.0/CLAUDE.md

@@ -0,0 +1,355 @@
+# tiny-py — Client Library Specification
+
+A production-grade Python SDK for the Tiny ERP API v2.
+Designed to be installable via pip, fully typed, and safe for use in FastAPI services and message queue workers (RabbitMQ, Celery, etc.).
+
+---
+
+## Design Principles
+
+- **Single entry point.** All interaction goes through `TinyClient`. No module-level functions or globals.
+- **Instance-scoped state.** Rate limiter, session, and credentials live on the client instance — never as module globals. Multiple tokens and plans can coexist in the same process.
+- **No I/O side effects.** The library only communicates with the Tiny API. File writes, queues, and databases are the caller's responsibility.
+- **Typed contracts.** All public methods accept and return Pydantic v2 models. Raw dicts do not leak outside the library.
+- **Explicit over implicit.** No environment variable sniffing inside the client. Configuration is passed at instantiation.
+- **Sync-first, async-ready.** The default implementation is synchronous (safe for workers). An async variant (`AsyncTinyClient`) shares the same resource interface via an abstract base.
+
+---
+
+## Package Structure
+
+```
+tiny_py/
+├── __init__.py                  # Exports: TinyClient, AsyncTinyClient, exceptions, models
+├── py.typed                     # PEP 561 marker
+├── _client.py                   # TinyClient and AsyncTinyClient
+├── _http.py                     # HTTPAdapter: session, retry, timeout, rate limiting
+├── _rate_limiter.py             # RateLimiter (sync) and AsyncRateLimiter
+├── exceptions.py                # Full exception hierarchy
+├── resources/
+│   ├── __init__.py
+│   ├── _base.py                 # BaseResource — shared _get / _post + pagination helper
+│   ├── products.py              # ProductsResource
+│   └── orders.py                # OrdersResource
+└── models/
+    ├── __init__.py
+    ├── product.py               # Product, ProductStock, StockDeposit, StockUpdateRequest, PriceUpdateRequest
+    └── order.py                 # Order, OrderItem, OrderClient, OrderEcommerce, OrderMarker
+```
+
+---
+
+## TinyClient Interface
+
+```python
+from tiny_py import TinyClient
+
+client = TinyClient(
+    token="your_token",
+    plan="advanced",          # "free" | "basic" | "advanced"
+    timeout=(5.0, 30.0),      # (connect_timeout, read_timeout)
+    max_retries=5,
+    base_url="https://api.tiny.com.br/api2",  # override for tests
+)
+
+# Resources are lazy-instantiated attributes
+client.products   # -> ProductsResource
+client.orders     # -> OrdersResource
+```
+
+`TinyClient` must not accept `session`, `httpx.Client`, or any transport object at `__init__` — transport is an internal concern managed by `_http.py`.
+
+---
+
+## Exception Hierarchy
+
+All exceptions inherit from `TinyError` so callers can catch broadly or narrowly.
+
+```python
+# exceptions.py
+
+class TinyError(Exception):
+    """Base for all tiny-py errors."""
+
+class TinyAPIError(TinyError):
+    """The API returned status != OK. Business-level error — do not retry."""
+    def __init__(self, message: str, endpoint: str, errors: list[str]):
+        ...
+
+class TinyAuthError(TinyAPIError):
+    """Invalid or expired token."""
+
+class TinyRateLimitError(TinyError):
+    """HTTP 429 received after all retry attempts are exhausted."""
+
+class TinyServerError(TinyError):
+    """HTTP 5xx after all retry attempts are exhausted."""
+
+class TinyTimeoutError(TinyError):
+    """Request timed out after all retry attempts."""
+```
+
+**Rule for callers (e.g. RabbitMQ workers):**
+- `TinyAPIError` → send to Dead Letter Queue, do not retry.
+- `TinyRateLimitError | TinyServerError | TinyTimeoutError` → re-enqueue with backoff.
+
+---
+
+## HTTP Layer (`_http.py`)
+
+Wraps `requests.Session` with:
+- Persistent connection pooling (`HTTPAdapter` with `pool_connections`, `pool_maxsize`)
+- Automatic injection of `token` and `formato=json`
+- Retry loop with **exponential backoff** on `429`, `500`, `502`, `503`, `504`
+- Separation of `connect_timeout` and `read_timeout` via tuple
+- Rate limiter call before every request
+
+```python
+class HTTPAdapter:
+    def __init__(self, token: str, rate_limiter: RateLimiter, timeout: tuple, max_retries: int, base_url: str): ...
+    def get(self, endpoint: str, params: dict) -> dict: ...
+    def post(self, endpoint: str, data: dict) -> dict: ...
+    def close(self): ...
+
+    def __enter__(self): return self
+    def __exit__(self, *_): self.close()
+```
+
+`HTTPAdapter` returns the inner `retorno` dict on success. It raises typed exceptions — never returns raw error responses.
+
+---
+
+## Rate Limiter (`_rate_limiter.py`)
+
+Token bucket per client instance. Plan-based defaults, but fully overridable.
+
+```python
+PLAN_RPM = {
+    "free":     30,
+    "basic":    60,
+    "advanced": 120,
+}
+
+class RateLimiter:
+    """Thread-safe token bucket for synchronous use."""
+    def __init__(self, rpm: int): ...
+    def acquire(self): ...     # blocks until a slot is available
+
+class AsyncRateLimiter:
+    """asyncio-safe token bucket for async use."""
+    def __init__(self, rpm: int): ...
+    async def acquire(self): ...
+```
+
+**Note for multi-process workers:** Each process has its own `TinyClient` instance and its own in-memory rate limiter. If many workers run in parallel against the same Tiny token, rate limits are not coordinated across processes. For high-concurrency scenarios, replace the in-process limiter with a Redis-backed sliding window (e.g., `redis-py` with a Lua script) and pass a custom `rpm` override to the client.
+
+---
+
+## Resources
+
+### Base Resource (`resources/_base.py`)
+
+```python
+class BaseResource:
+    def __init__(self, http: HTTPAdapter): ...
+
+    def _paginate(self, endpoint: str, collection_key: str, item_key: str, params: dict) -> Iterator[dict]:
+        """
+        Generic pagination iterator. Yields raw item dicts page by page.
+        Stops when the current page equals numero_paginas.
+        """
+```
+
+All resource methods that return lists use `_paginate` internally. Public methods expose either:
+- A **generator** variant (`iter_*`) for memory-efficient streaming.
+- A **list** variant that materialises the full result set (convenience wrapper around the generator).
+
+---
+
+### Products Resource (`resources/products.py`)
+
+```python
+class ProductsResource(BaseResource):
+
+    def search(self, situacao: str = "A") -> list[Product]:
+        """Returns all products matching the filter (auto-paginated)."""
+
+    def iter_search(self, situacao: str = "A") -> Iterator[Product]:
+        """Memory-efficient generator. Preferred for large catalogues."""
+
+    def get(self, product_id: str) -> Product:
+        """Fetches full product data (produto.obter.php)."""
+
+    def get_stock(self, product_id: str) -> ProductStock:
+        """Fetches stock per deposit (produto.obter.estoque.php)."""
+
+    def update_stock(self, product_id: str, request: StockUpdateRequest) -> None:
+        """Updates deposit balances (produto.atualizar.estoque.php)."""
+
+    def update_price(self, product_id: str, request: PriceUpdateRequest) -> None:
+        """Updates regular and promotional prices (produto.atualizar.preco.php)."""
+```
+
+---
+
+### Orders Resource (`resources/orders.py`)
+
+```python
+class OrdersResource(BaseResource):
+
+    def search(self, date_from: date, date_to: date) -> list[Order]:
+        """Returns all orders in the date range (auto-paginated)."""
+
+    def iter_search(self, date_from: date, date_to: date) -> Iterator[Order]:
+        """Memory-efficient generator."""
+
+    def get(self, order_id: str) -> Order:
+        """Fetches full order details (pedido.obter.php)."""
+```
+
+---
+
+## Models (`models/`)
+
+All models use **Pydantic v2**. Field aliases match the Tiny API's Portuguese naming, with English Python attribute names exposed to callers.
+
+```python
+# models/product.py
+class StockDeposit(BaseModel):
+    name: str       = Field(alias="nome")
+    balance: float  = Field(alias="saldo")
+    ignore: bool    = Field(alias="desconsiderar")  # "S"/"N" -> bool validator
+    company: str    = Field(alias="empresa")
+
+class ProductStock(BaseModel):
+    product_id: str           = Field(alias="id")
+    sku: str                  = Field(alias="codigo")
+    name: str                 = Field(alias="nome")
+    balance: float            = Field(alias="saldo")
+    reserved_balance: float   = Field(alias="saldoReservado")
+    deposits: list[StockDeposit] = Field(alias="depositos", default_factory=list)
+
+class Product(BaseModel):
+    id: str
+    name: str                 = Field(alias="nome")
+    sku: str                  = Field(alias="codigo")
+    price: float              = Field(alias="preco")
+    promo_price: float | None = Field(alias="preco_promocional", default=None)
+    cost_price: float | None  = Field(alias="preco_custo", default=None)
+    unit: str                 = Field(alias="unidade")
+    gtin: str | None          = Field(alias="gtin", default=None)
+    ncm: str | None           = Field(alias="ncm", default=None)
+    status: str               = Field(alias="situacao")
+    category: str | None      = Field(alias="categoria", default=None)
+    brand: str | None         = Field(alias="marca", default=None)
+
+class StockUpdateRequest(BaseModel):
+    deposits: list[StockDepositUpdate]
+
+class PriceUpdateRequest(BaseModel):
+    price: float
+    promo_price: float | None = None
+```
+
+```python
+# models/order.py
+class OrderItem(BaseModel):
+    product_id: str    = Field(alias="id_produto")
+    sku: str           = Field(alias="codigo")
+    description: str   = Field(alias="descricao")
+    quantity: float    = Field(alias="quantidade")
+    unit_price: float  = Field(alias="valor_unitario")
+
+class OrderEcommerce(BaseModel):
+    id: str
+    name: str          = Field(alias="nomeEcommerce")
+    order_number: str  = Field(alias="numeroPedidoEcommerce")
+
+class Order(BaseModel):
+    id: str
+    number: str        = Field(alias="numero")
+    order_date: date   = Field(alias="data_pedido")   # validator: "DD/MM/YYYY" -> date
+    status: str        = Field(alias="situacao")
+    items: list[OrderItem] = Field(alias="itens", default_factory=list)
+    ecommerce: OrderEcommerce | None = Field(alias="ecommerce", default=None)
+    total: float       = Field(alias="total_pedido")
+    tracking_code: str = Field(alias="codigo_rastreamento", default="")
+```
+
+---
+
+## Async Client (`AsyncTinyClient`)
+
+Mirrors `TinyClient` exactly. Uses `httpx.AsyncClient` internally instead of `requests.Session`, and `AsyncRateLimiter` instead of `RateLimiter`. All resource methods become coroutines.
+
+```python
+async with AsyncTinyClient(token="...", plan="advanced") as client:
+    products = await client.products.search()
+    order = await client.orders.get("970977594")
+```
+
+FastAPI endpoints should use `AsyncTinyClient` to avoid blocking the event loop.
+
+---
+
+## FastAPI Integration Pattern
+
+```python
+# deps.py
+from functools import lru_cache
+from tiny_py import AsyncTinyClient
+
+@lru_cache(maxsize=1)
+def _client() -> AsyncTinyClient:
+    return AsyncTinyClient(token=settings.TINY_TOKEN, plan=settings.TINY_PLAN)
+
+async def get_tiny() -> AsyncTinyClient:
+    return _client()
+
+# router.py
+@router.get("/products/{product_id}/stock")
+async def get_stock(
+    product_id: str,
+    client: AsyncTinyClient = Depends(get_tiny),
+):
+    return await client.products.get_stock(product_id)
+```
+
+---
+
+## RabbitMQ Worker Pattern
+
+```python
+# worker.py
+from tiny_py import TinyClient
+from tiny_py.exceptions import TinyAPIError, TinyRateLimitError
+
+client = TinyClient(token=os.environ["TINY_TOKEN"], plan="advanced")
+
+def handle_message(body: dict):
+    try:
+        order = client.orders.get(body["order_id"])
+        publish_result(order)
+    except TinyAPIError:
+        nack(requeue=False)   # business error -> DLQ
+    except (TinyRateLimitError, TinyServerError, TinyTimeoutError):
+        nack(requeue=True)    # transient error -> re-enqueue with backoff
+```
+
+One `TinyClient` instance per worker process. Never share an instance across process boundaries. For coordinated rate limiting across many workers on the same token, inject a Redis-backed limiter.
+
+---
+
+## Testing
+
+- Unit tests mock `_http.HTTPAdapter` at the resource level — never mock `requests` directly.
+- Fixtures provide pre-built `HTTPAdapter` fakes returning model-valid dicts.
+- Integration tests are marked `@pytest.mark.integration`, skipped in CI unless `TINY_TOKEN` is set.
+- Use `base_url` override in `TinyClient` to point at a local stub server (e.g. `pytest-httpserver`) for contract tests.
+
+---
+
+## API Version
+
+This library targets **Tiny ERP API v2** (`https://api.tiny.com.br/api2`).
+API v3 exists but uses OAuth 2.0 and a different resource structure. Do not mix v2 and v3 calls in the same client.

tiny_erp_py-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: tiny-erp-py
+Version: 0.1.0
+Summary: Production-grade Python SDK for the Tiny ERP API v2
+Author: Joaoaalves
+License: MIT
+Keywords: api,erp,sdk,tiny,tiny-erp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tiny-py
+
+> Production-grade Python SDK for the **Tiny ERP API v2**.
+> Fully typed, async-ready, and safe for FastAPI services and message queue workers.
+
+[![PyPI version](https://img.shields.io/pypi/v/tiny-erp-py.svg)](https://pypi.org/project/tiny-erp-py/)
+[![Python](https://img.shields.io/pypi/pyversions/tiny-erp-py.svg)](https://pypi.org/project/tiny-erp-py/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## Features
+
+- **Single entry point** — all interaction through `TinyClient` or `AsyncTinyClient`
+- **Typed contracts** — every method accepts and returns Pydantic v2 models
+- **Automatic rate limiting** — token bucket per client instance, plan-aware (30 / 60 / 120 RPM)
+- **Retry with exponential backoff** — automatic on 429 / 5xx responses
+- **Sync + Async** — `TinyClient` for workers, `AsyncTinyClient` for FastAPI
+- **No global state** — multiple tokens and plans can coexist in the same process
+
+## Installation
+
+```bash
+pip install tiny-py
+```
+
+Requires Python 3.11+.
+
+## Quick example
+
+```python
+from tiny_py import TinyClient
+
+client = TinyClient(token="your_token", plan="advanced")
+
+# Stream all active products
+for product in client.products.iter_search():
+    print(product.sku, product.name, product.price)
+
+# Fetch a single order
+order = client.orders.get("970977594")
+print(order.number, order.total)
+```
+
+### Async (FastAPI)
+
+```python
+from tiny_py import AsyncTinyClient
+
+async with AsyncTinyClient(token="your_token", plan="advanced") as client:
+    products = await client.products.search()
+    order = await client.orders.get("970977594")
+```
+
+## API coverage (v0.1.0)
+
+| Resource | Methods |
+|----------|---------|
+| **Products** | `search`, `iter_search`, `get`, `get_stock`, `update_stock`, `update_price` |
+| **Orders** | `search`, `iter_search`, `get` |
+
+See the [roadmap](https://github.com/your-org/tiny-py) for planned resources.
+
+## Error handling
+
+```python
+from tiny_py.exceptions import TinyAPIError, TinyRateLimitError, TinyServerError, TinyTimeoutError
+
+try:
+    order = client.orders.get(order_id)
+except TinyAPIError:
+    # Business error — do not retry (send to DLQ)
+    ...
+except (TinyRateLimitError, TinyServerError, TinyTimeoutError):
+    # Transient error — re-enqueue with backoff
+    ...
+```
+
+## License
+
+MIT