docges-api-py 0.1.3

Async, typed Python client for DocGes REST API

docges-api-py

Async, typed Python client for the DocGes REST API.

Work in progress — bootstrapped via SDD (Spec-Driven Development).
Phase 1-4 completed: async client with auth, retry, token refresh, and tests. Phase 5 completed: All core endpoints implemented.

Features

• ✅ Async HTTP client using httpx
• ✅ Typed request/response models with Pydantic v2
• ✅ Configurable retries and timeouts
• ✅ Session-based auth using loginResponse passed to Content endpoints
• ✅ Full test coverage (pytest + respx)
• ✅ Complete DocGes API client (upload, download, search, categories)

Implemented endpoints

Auth

• auth() — authenticate against /Auth/Login

Content Tree

• get_initial_cats() — load initial categories via /Content/LoadIniCats
• get_cat_info(sid) — load category children via /Content/LoadChilds

Document Operations

• upload_file(category_sid, file_path) — upload via /Content/UploadExtended
• download_content(sid) — download via /Content/Download (returns ResFileDownload)
• get_document(sid) — deprecated wrapper (calls download_content())

Search

• search_content(field_values, date_values) — search via /Content/SearchContent

Category Management

• create_category(parent_sid, name) — create via /Content/CreateCategory
• rename_category(sid, new_name) — rename via /Content/RenameCategory
• delete_category(sid) — delete via /Content/DeleteCategory

Document Management

• remove_document(sid) — remove via /Content/RemoveDocument
• move_content(content_sid, destination_sid) — move via /Content/Move
• update_content(sid, erp_relation, erp_property) — update via /Content/Update

Quick start

pip install -e ".[dev]"

import asyncio
from docges_api_py import AsyncDocGes


async def main():
    async with AsyncDocGes(
        "https://docges.example.com", "user", "password", "appid"
    ) as client:
        # Auth
        auth_resp = await client.auth()
        # The API is session-based: auth_resp contains user_info and ware_house_info
        print(f"User: {auth_resp.user_info.get('Nombre')}")
        print(f"Warehouse: {auth_resp.ware_house_info.get('Nombre')}")

        # Load initial categories (the client injects loginDocGesData + loginResponse automatically)
        # Some DocGes bridge servers expect both fields in requestModel for Content endpoints.
        cats = await client.get_initial_cats()
        print(f"Initial categories: {len(cats.CategoriasHijas)}")

        # Search documents
        results = await client.search_content(
            field_values=[{"field": "name", "mode": "contains", "text": "invoice"}]
        )
        print(f"Search results: {len(results.results)}")


asyncio.run(main())

See docs/quickstart.md or examples/quickstart.py for a more complete example.

For a working end-to-end demo (login + fetch root categories), see examples/initial_categories.py.

Development

pip install -e ".[dev]"
ruff check src/ tests/
mypy src/
pytest --cov=docges_api_py

Migration

The library is being migrated from a sync requests-based client (see wm-sync reference code). See docs/MIGRATION.md for details.

Key changes:

• Replaced requests (sync) with httpx.AsyncClient
• Replaced raw __dict__ serialization with Pydantic v2 models
• Replaced silent return None with typed exceptions (AuthenticationError, RequestError)
• Added configurable retries with exponential backoff

Project structure

docges-api-py/
├── src/docges_api_py/
│   ├── __init__.py          # Exports AsyncDocGes, models (ResCat, ResFileDownload, etc.)
│   ├── client.py            # AsyncDocGes client (auth + all endpoints)
│   └── models/
│       ├── auth.py           # AuthRequest, AuthResponse
│       ├── document.py      # Document
│       ├── requests.py      # Request models (ReqUpload, ReqSearchContent, etc.)
│       ├── responses.py     # Response models (ResCat, ResFileDownload, etc.)
│       └── __init__.py      # Model exports
├── tests/
│   ├── conftest.py
│   ├── test_client_auth.py
│   ├── test_initial_cats.py
│   ├── test_content_methods.py
│   ├── test_remaining_methods.py
│   ├── test_models_requests.py
│   ├── test_models_responses.py
│   ├── test_models_init.py
│   ├── test_endpoints.py
│   ├── test_retry.py
│   └── test_token_refresh.py
├── examples/
│   └── quickstart.py
├── docs/
│   └── MIGRATION.md
├── pyproject.toml
├── ruff.toml
├── mypy.ini
└── README.md

Contributing

See CONTRIBUTING.md for guidelines.