moco-py 1.0.0__tar.gz

moco_py-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run semantic-release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          uv run semantic-release version
+          uv run semantic-release publish
+
+      - name: Publish to PyPI
+        if: hashFiles('dist/*') != ''
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

moco_py-1.0.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking / Linting
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# AI Code Assistants
+.claude/
+.cursor/
+.aider*
+.codeium/
+.continue/
+.copilot/
+.tabby/
+CLAUDE.md
+AGENTS.md
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+
+# official docs for reference
+mocoapp-api-docs-master/

moco_py-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.13.9
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]

moco_py-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-03-01)
+
+- Initial Release

moco_py-1.0.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: moco-py
+Version: 1.0.0
+Summary: Python client library for the MOCO ERP API
+Project-URL: Homepage, https://github.com/bandbyte/moco-py
+Project-URL: Documentation, https://github.com/bandbyte/moco-py
+Project-URL: Repository, https://github.com/bandbyte/moco-py
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# moco-py
+
+Python client library for the [MOCO ERP API](https://www.mocoapp.com).
+
+## Installation
+
+```bash
+pip install moco-py
+```
+
+## Quick Start
+
+```python
+from moco_py import Moco
+
+client = Moco(domain="yourcompany", api_key="your-api-key")
+```

moco_py-1.0.0/README.md

@@ -0,0 +1,17 @@
+# moco-py
+
+Python client library for the [MOCO ERP API](https://www.mocoapp.com).
+
+## Installation
+
+```bash
+pip install moco-py
+```
+
+## Quick Start
+
+```python
+from moco_py import Moco
+
+client = Moco(domain="yourcompany", api_key="your-api-key")
+```

moco_py-1.0.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "moco-py"
+version = "1.0.0"
+description = "Python client library for the MOCO ERP API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/bandbyte/moco-py"
+Documentation = "https://github.com/bandbyte/moco-py"
+Repository = "https://github.com/bandbyte/moco-py"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/moco_py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: tests that hit a live MOCO API (require MOCO_API_KEY and MOCO_DOMAIN env vars)",
+]
+
+[tool.ruff]
+src = ["src"]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["moco_py"]
+mypy_path = "src"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+tag_format = "v$version"
+update_changelog_on_bump = true
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/moco_py/__init__.py:__version__"]
+tag_format = "v{version}"
+build_command = "uv build"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+
+[tool.semantic_release.branches.main]
+match = "main"
+
+[dependency-groups]
+dev = [
+    "commitizen>=4.13.9",
+    "mypy>=1.0",
+    "pre-commit>=4.5.1",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "python-semantic-release>=10.5.3",
+    "respx>=0.22",
+    "ruff>=0.8",
+]

moco_py-1.0.0/src/moco_py/__init__.py

@@ -0,0 +1,36 @@
+"""MOCO ERP API client library."""
+
+from ._pagination import AsyncPage, SyncPage
+from ._response import MocoResponse
+from .client import AsyncMoco, Moco
+from .exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    MocoError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AsyncMoco",
+    "AsyncPage",
+    "Moco",
+    "MocoResponse",
+    "SyncPage",
+    "__version__",
+    "APIConnectionError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "MocoError",
+    "NotFoundError",
+    "PermissionError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+]

moco_py-1.0.0/src/moco_py/_constants.py

@@ -0,0 +1,9 @@
+"""Internal constants for the MOCO API client."""
+
+BASE_URL_TEMPLATE = "https://{domain}.mocoapp.com/api/v1"
+ENV_API_KEY = "MOCO_API_KEY"
+ENV_DOMAIN = "MOCO_DOMAIN"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_PER_PAGE = 100
+RETRY_STATUS_CODES = {429, 500, 502, 503, 504}

moco_py-1.0.0/src/moco_py/_pagination.py

@@ -0,0 +1,160 @@
+"""Header-based pagination for the MOCO API."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import AsyncIterator, Iterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+import httpx
+from pydantic import TypeAdapter
+
+if TYPE_CHECKING:
+    from ._transport import AsyncTransport, SyncTransport
+
+T = TypeVar("T")
+
+_LINK_NEXT_RE = re.compile(r'<[^>]*[?&]page=(\d+)[^>]*>;\s*rel="next"')
+
+
+def _parse_link_next(link: str | None) -> int | None:
+    """Extract the next page number from a Link header with rel="next"."""
+    if link is None:
+        return None
+    match = _LINK_NEXT_RE.search(link)
+    if match is None:
+        return None
+    return int(match.group(1))
+
+
+@dataclass(frozen=True)
+class PageInfo:
+    """Metadata from pagination response headers."""
+
+    page: int
+    per_page: int
+    total: int
+
+
+class SyncPage(Generic[T]):
+    """A single page of results from a paginated MOCO API endpoint."""
+
+    def __init__(
+        self,
+        *,
+        items: list[T],
+        http_response: httpx.Response,
+        transport: SyncTransport,
+        path: str,
+        params: dict[str, object],
+        cast_to: type[T],
+    ) -> None:
+        self.items = items
+        self.http_response = http_response
+        self._transport = transport
+        self._path = path
+        self._params = params
+        self._cast_to = cast_to
+
+        headers = http_response.headers
+        self.page_info = PageInfo(
+            page=int(headers.get("X-Page", "1")),
+            per_page=int(headers.get("X-Per-Page", "100")),
+            total=int(headers.get("X-Total", str(len(items)))),
+        )
+        self._next_page = _parse_link_next(headers.get("Link"))
+
+    @property
+    def has_next(self) -> bool:
+        return self._next_page is not None
+
+    def next_page(self) -> SyncPage[T]:
+        """Fetch the next page of results."""
+        if self._next_page is None:
+            raise StopIteration("No more pages")
+        params = {**self._params, "page": self._next_page}
+        response = self._transport.request_raw("GET", self._path, params=params)
+        adapter = TypeAdapter(list[self._cast_to])  # type: ignore[name-defined]
+        items = adapter.validate_json(response.content)
+        return SyncPage(
+            items=items,
+            http_response=response,
+            transport=self._transport,
+            path=self._path,
+            params=self._params,
+            cast_to=self._cast_to,
+        )
+
+    def __iter__(self) -> Iterator[T]:
+        yield from self.items
+
+    def auto_paging_iter(self) -> Iterator[T]:
+        """Iterate over all items across all pages."""
+        page: SyncPage[T] = self
+        while True:
+            yield from page.items
+            if not page.has_next:
+                break
+            page = page.next_page()
+
+
+class AsyncPage(Generic[T]):
+    """A single page of results from a paginated MOCO API endpoint (async)."""
+
+    def __init__(
+        self,
+        *,
+        items: list[T],
+        http_response: httpx.Response,
+        transport: AsyncTransport,
+        path: str,
+        params: dict[str, object],
+        cast_to: type[T],
+    ) -> None:
+        self.items = items
+        self.http_response = http_response
+        self._transport = transport
+        self._path = path
+        self._params = params
+        self._cast_to = cast_to
+
+        headers = http_response.headers
+        self.page_info = PageInfo(
+            page=int(headers.get("X-Page", "1")),
+            per_page=int(headers.get("X-Per-Page", "100")),
+            total=int(headers.get("X-Total", str(len(items)))),
+        )
+        self._next_page = _parse_link_next(headers.get("Link"))
+
+    @property
+    def has_next(self) -> bool:
+        return self._next_page is not None
+
+    async def next_page(self) -> AsyncPage[T]:
+        if self._next_page is None:
+            raise StopAsyncIteration("No more pages")
+        params = {**self._params, "page": self._next_page}
+        response = await self._transport.request_raw("GET", self._path, params=params)
+        adapter = TypeAdapter(list[self._cast_to])  # type: ignore[name-defined]
+        items = adapter.validate_json(response.content)
+        return AsyncPage(
+            items=items,
+            http_response=response,
+            transport=self._transport,
+            path=self._path,
+            params=self._params,
+            cast_to=self._cast_to,
+        )
+
+    def __iter__(self) -> Iterator[T]:
+        yield from self.items
+
+    async def auto_paging_iter(self) -> AsyncIterator[T]:
+        page: AsyncPage[T] = self
+        while True:
+            for item in page.items:
+                yield item
+            if not page.has_next:
+                break
+            page = await page.next_page()

moco_py-1.0.0/src/moco_py/_resource.py

@@ -0,0 +1,157 @@
+"""Base resource classes for sync and async API access."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import TypeAdapter
+
+from ._pagination import AsyncPage, SyncPage
+from ._response import MocoResponse
+from ._transport import AsyncTransport, SyncTransport
+
+T = TypeVar("T")
+
+
+class SyncResource:
+    """Base class for synchronous API resource namespaces."""
+
+    def __init__(self, transport: SyncTransport) -> None:
+        self._transport = transport
+
+    def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        cast_to: type[T],
+    ) -> MocoResponse[T]:
+        return self._transport.request("GET", path, params=params, cast_to=cast_to)
+
+    def _get_list(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        cast_to: type[T],
+    ) -> SyncPage[T]:
+        response = self._transport.request_raw("GET", path, params=params)
+        adapter = TypeAdapter(list[cast_to])  # type: ignore[valid-type]
+        items = adapter.validate_json(response.content)
+        return SyncPage(
+            items=items,
+            http_response=response,
+            transport=self._transport,
+            path=path,
+            params=params or {},
+            cast_to=cast_to,
+        )
+
+    def _post(
+        self,
+        path: str,
+        *,
+        json_data: Any = None,
+        cast_to: type[T],
+    ) -> MocoResponse[T]:
+        return self._transport.request(
+            "POST", path, json_data=json_data, cast_to=cast_to
+        )
+
+    def _put(
+        self,
+        path: str,
+        *,
+        json_data: Any = None,
+        cast_to: type[T],
+    ) -> MocoResponse[T]:
+        return self._transport.request(
+            "PUT", path, json_data=json_data, cast_to=cast_to
+        )
+
+    def _patch(
+        self,
+        path: str,
+        *,
+        json_data: Any = None,
+        cast_to: type[T],
+    ) -> MocoResponse[T]:
+        return self._transport.request(
+            "PATCH", path, json_data=json_data, cast_to=cast_to
+        )
+
+    def _delete(self, path: str) -> MocoResponse[None]:
+        return self._transport.request("DELETE", path, cast_to=None)
+
+
+class AsyncResource:
+    """Base class for asynchronous API resource namespaces."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._transport = transport
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        cast_to: type[T],
+    ) -> MocoResponse[Any]:
+        return await self._transport.request(
+            "GET", path, params=params, cast_to=cast_to
+        )
+
+    async def _get_list(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        cast_to: type[T],
+    ) -> AsyncPage[T]:
+        response = await self._transport.request_raw("GET", path, params=params)
+        adapter = TypeAdapter(list[cast_to])  # type: ignore[valid-type]
+        items = adapter.validate_json(response.content)
+        return AsyncPage(
+            items=items,
+            http_response=response,
+            transport=self._transport,
+            path=path,
+            params=params or {},
+            cast_to=cast_to,
+        )
+
+    async def _post(
+        self,
+        path: str,
+        *,
+        json_data: Any = None,
+        cast_to: type[T],
+    ) -> MocoResponse[Any]:
+        return await self._transport.request(
+            "POST", path, json_data=json_data, cast_to=cast_to
+        )
+
+    async def _put(
+        self,
+        path: str,
+        *,
+        json_data: Any = None,
+        cast_to: type[T],
+    ) -> MocoResponse[Any]:
+        return await self._transport.request(
+            "PUT", path, json_data=json_data, cast_to=cast_to
+        )
+
+    async def _patch(
+        self,
+        path: str,
+        *,
+        json_data: Any = None,
+        cast_to: type[T],
+    ) -> MocoResponse[Any]:
+        return await self._transport.request(
+            "PATCH", path, json_data=json_data, cast_to=cast_to
+        )
+
+    async def _delete(self, path: str) -> MocoResponse[Any]:
+        return await self._transport.request("DELETE", path, cast_to=None)

moco_py-1.0.0/src/moco_py/_response.py

@@ -0,0 +1,27 @@
+"""Response wrapper providing typed access alongside raw httpx.Response."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+import httpx
+
+T = TypeVar("T")
+
+
+class MocoResponse(Generic[T]):
+    """Wraps a parsed Pydantic model with access to the raw HTTP response."""
+
+    __slots__ = ("parsed", "http_response")
+
+    def __init__(self, *, parsed: T, http_response: httpx.Response) -> None:
+        self.parsed = parsed
+        self.http_response = http_response
+
+    @property
+    def status_code(self) -> int:
+        return self.http_response.status_code
+
+    @property
+    def headers(self) -> httpx.Headers:
+        return self.http_response.headers