pybc365 0.1.0__tar.gz

pybc365-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konspec - FPA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pybc365-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: pybc365
+Version: 0.1.0
+Summary: A modern, fully typed Python client for Microsoft Dynamics 365 Business Central.
+Keywords: business-central,dynamics-365,microsoft-dynamics,erp,api,odata,python
+Author: Akshay Prabhu
+Author-email: Akshay Prabhu <akshay.prabhu@konspec.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/konfpa/pybc365
+Project-URL: Repository, https://github.com/konfpa/pybc365
+Project-URL: Issues, https://github.com/konfpa/pybc365/issues
+Description-Content-Type: text/markdown
+
+# pybc365
+
+A modern, fully typed Python client for Microsoft Dynamics 365 Business Central.
+
+[![CI](https://github.com/konfpa/pybc365/actions/workflows/ci.yml/badge.svg)](https://github.com/konfpa/pybc365/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pybc365.svg)](https://pypi.org/project/pybc365/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pybc365.svg)](https://pypi.org/project/pybc365/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+
+## What is pybc365?
+
+`pybc365` is a Python library for talking to Microsoft Dynamics 365
+Business Central. It's meant to be a dependable building block for the
+kinds of code that need to move data in and out of BC: applications,
+automation scripts, ETL/data pipelines, and backend services.
+
+The library is generic by design: it does not assume anything about a
+particular Business Central tenant, company, or set of custom entities.
+
+## Why pybc365?
+
+- **Python-friendly** - designed to feel natural in Python code, not like
+  a thin wrapper around BC's OData/REST conventions.
+- **Fully typed** - the whole library ships type annotations and a
+  `py.typed` marker, so type checkers understand it out of the box.
+- **Explicit over magical** - no hidden metaclass tricks or implicit
+  global state; what the code does is visible in the code.
+- **Minimal assumptions** - no baked-in entities, companies, or
+  environment configuration.
+- **Composable and minimal dependencies** - suitable for use as
+  infrastructure inside larger systems.
+
+`httpx` is the only runtime dependency. See
+[Project status](#project-status) for what v0.1 covers.
+
+## Installation
+
+```bash
+pip install pybc365
+```
+
+or, with uv:
+
+```bash
+uv add pybc365
+```
+
+`pybc365` itself does not require uv; it's a normal PyPI package.
+
+## Quick start
+
+```python
+import httpx
+
+from pybc365 import Client, F, desc
+
+with Client(
+    base_url="https://bc.example.com/BC240",
+    company="CRONUS International Ltd.",
+    auth=httpx.BasicAuth("webservice", "hunter2"),
+) as client:
+    customers = (
+        client.service("Customers")
+        .filter(F.Name.startswith("Contoso"), F.Blocked == "")
+        .select("No", "Name", "Balance")
+        .order_by(desc("Balance"))
+    )
+
+    print(customers.count())
+
+    for row in customers:
+        print(row["No"], row["Name"], row["Balance"])
+```
+
+`base_url` is the server root, stopping **before** the `ODataV4` segment.
+Construction sends no request; the first request goes out when the loop asks
+for its first row.
+
+Reading amounts? Pass `parse_float=Decimal`. The default `float` loses the
+digits of an `Edm.Decimal` before your code ever sees them. See
+[Types on the wire](./docs/types-on-the-wire.md).
+
+If `Client` collides with `httpx.Client` in your module, import the package
+instead and write `pybc365.Client`.
+
+## Documentation
+
+The [documentation](./docs/index.md) ships in this repository.
+
+| Page | Answers |
+|---|---|
+| [Getting started](./docs/getting-started.md) | How do I install it and read my first rows? |
+| [Authentication](./docs/authentication.md) | Which auth recipe is tested, and against what? |
+| [Queries](./docs/queries.md) | How do I select, order, page and count? |
+| [Filters](./docs/filters.md) | What literal does my value become, and what does Business Central refuse? |
+| [Types on the wire](./docs/types-on-the-wire.md) | What Python type will this value be? |
+| [Errors](./docs/errors.md) | Which exception is this, and what caused it? |
+| [Not shipped: the REST surface](./docs/rest-surface.md) | Why is there no `/api/v2.0` client? |
+| [API reference](./docs/api.md) | The full signature of every public name. |
+
+## Project status
+
+**v0.1: sync, fully typed, read-only.** The library reads published web
+services (OData V4) from one company on one server, with filters, selection,
+ordering, server-driven paging, retry and one exception hierarchy.
+
+Not in v0.1: create, update and delete; an async client; the REST API
+(`/api/v2.0`); `$expand`; and any fetch of `$metadata`. `AsyncClient` is the
+reserved name for the async client, and no such class ships today.
+
+"Fully typed" means the library checks the **call shape** and nothing about the
+**data**. A misspelled web service, field, projection or ordering key all pass a
+strict `mypy` check with `dict[str, Any]` rows. A `row=` converter is the only
+thing that closes that gap.
+
+Every Business Central fact in this documentation is an observation of **BC
+22.2 on-premises**, never a Business Central guarantee.
+
+`pybc365` is not affiliated with or endorsed by Microsoft.
+
+## Design principles
+
+- Typed by default, everywhere in the public API.
+- Explicit over magical.
+- Minimal runtime dependencies.
+- Endpoint-agnostic: no assumptions about specific BC entities or setups.
+- Composable pieces over one large client object.
+- Predictable, deliberately designed public APIs.
+- Testable architecture, with behavior-focused tests.
+
+## Development
+
+```bash
+git clone https://github.com/konfpa/pybc365.git
+cd pybc365
+uv sync
+uv run prek install
+```
+
+Common commands:
+
+```bash
+uv run ruff format .          # format
+uv run ruff check .           # lint
+uv run mypy src scripts tests  # type check
+uv run pytest                  # test (with coverage)
+uv run prek run --all-files    # all pre-commit hooks
+```
+
+See [`AGENTS.md`](./AGENTS.md) for the fuller set of engineering
+principles and quality expectations this project follows.
+
+## Contributing
+
+Contributions are welcome. Please read [`AGENTS.md`](./AGENTS.md) for the
+project's engineering principles before opening a pull request, and see
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for the contribution workflow.
+
+## Security
+
+See [`SECURITY.md`](./SECURITY.md) for how to report a vulnerability.
+
+## License
+
+Licensed under the [MIT License](./LICENSE).
+
+`pybc365` is an independent open-source project and is not affiliated
+with or endorsed by Microsoft.

pybc365-0.1.0/README.md

@@ -0,0 +1,170 @@
+# pybc365
+
+A modern, fully typed Python client for Microsoft Dynamics 365 Business Central.
+
+[![CI](https://github.com/konfpa/pybc365/actions/workflows/ci.yml/badge.svg)](https://github.com/konfpa/pybc365/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pybc365.svg)](https://pypi.org/project/pybc365/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pybc365.svg)](https://pypi.org/project/pybc365/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+
+## What is pybc365?
+
+`pybc365` is a Python library for talking to Microsoft Dynamics 365
+Business Central. It's meant to be a dependable building block for the
+kinds of code that need to move data in and out of BC: applications,
+automation scripts, ETL/data pipelines, and backend services.
+
+The library is generic by design: it does not assume anything about a
+particular Business Central tenant, company, or set of custom entities.
+
+## Why pybc365?
+
+- **Python-friendly** - designed to feel natural in Python code, not like
+  a thin wrapper around BC's OData/REST conventions.
+- **Fully typed** - the whole library ships type annotations and a
+  `py.typed` marker, so type checkers understand it out of the box.
+- **Explicit over magical** - no hidden metaclass tricks or implicit
+  global state; what the code does is visible in the code.
+- **Minimal assumptions** - no baked-in entities, companies, or
+  environment configuration.
+- **Composable and minimal dependencies** - suitable for use as
+  infrastructure inside larger systems.
+
+`httpx` is the only runtime dependency. See
+[Project status](#project-status) for what v0.1 covers.
+
+## Installation
+
+```bash
+pip install pybc365
+```
+
+or, with uv:
+
+```bash
+uv add pybc365
+```
+
+`pybc365` itself does not require uv; it's a normal PyPI package.
+
+## Quick start
+
+```python
+import httpx
+
+from pybc365 import Client, F, desc
+
+with Client(
+    base_url="https://bc.example.com/BC240",
+    company="CRONUS International Ltd.",
+    auth=httpx.BasicAuth("webservice", "hunter2"),
+) as client:
+    customers = (
+        client.service("Customers")
+        .filter(F.Name.startswith("Contoso"), F.Blocked == "")
+        .select("No", "Name", "Balance")
+        .order_by(desc("Balance"))
+    )
+
+    print(customers.count())
+
+    for row in customers:
+        print(row["No"], row["Name"], row["Balance"])
+```
+
+`base_url` is the server root, stopping **before** the `ODataV4` segment.
+Construction sends no request; the first request goes out when the loop asks
+for its first row.
+
+Reading amounts? Pass `parse_float=Decimal`. The default `float` loses the
+digits of an `Edm.Decimal` before your code ever sees them. See
+[Types on the wire](./docs/types-on-the-wire.md).
+
+If `Client` collides with `httpx.Client` in your module, import the package
+instead and write `pybc365.Client`.
+
+## Documentation
+
+The [documentation](./docs/index.md) ships in this repository.
+
+| Page | Answers |
+|---|---|
+| [Getting started](./docs/getting-started.md) | How do I install it and read my first rows? |
+| [Authentication](./docs/authentication.md) | Which auth recipe is tested, and against what? |
+| [Queries](./docs/queries.md) | How do I select, order, page and count? |
+| [Filters](./docs/filters.md) | What literal does my value become, and what does Business Central refuse? |
+| [Types on the wire](./docs/types-on-the-wire.md) | What Python type will this value be? |
+| [Errors](./docs/errors.md) | Which exception is this, and what caused it? |
+| [Not shipped: the REST surface](./docs/rest-surface.md) | Why is there no `/api/v2.0` client? |
+| [API reference](./docs/api.md) | The full signature of every public name. |
+
+## Project status
+
+**v0.1: sync, fully typed, read-only.** The library reads published web
+services (OData V4) from one company on one server, with filters, selection,
+ordering, server-driven paging, retry and one exception hierarchy.
+
+Not in v0.1: create, update and delete; an async client; the REST API
+(`/api/v2.0`); `$expand`; and any fetch of `$metadata`. `AsyncClient` is the
+reserved name for the async client, and no such class ships today.
+
+"Fully typed" means the library checks the **call shape** and nothing about the
+**data**. A misspelled web service, field, projection or ordering key all pass a
+strict `mypy` check with `dict[str, Any]` rows. A `row=` converter is the only
+thing that closes that gap.
+
+Every Business Central fact in this documentation is an observation of **BC
+22.2 on-premises**, never a Business Central guarantee.
+
+`pybc365` is not affiliated with or endorsed by Microsoft.
+
+## Design principles
+
+- Typed by default, everywhere in the public API.
+- Explicit over magical.
+- Minimal runtime dependencies.
+- Endpoint-agnostic: no assumptions about specific BC entities or setups.
+- Composable pieces over one large client object.
+- Predictable, deliberately designed public APIs.
+- Testable architecture, with behavior-focused tests.
+
+## Development
+
+```bash
+git clone https://github.com/konfpa/pybc365.git
+cd pybc365
+uv sync
+uv run prek install
+```
+
+Common commands:
+
+```bash
+uv run ruff format .          # format
+uv run ruff check .           # lint
+uv run mypy src scripts tests  # type check
+uv run pytest                  # test (with coverage)
+uv run prek run --all-files    # all pre-commit hooks
+```
+
+See [`AGENTS.md`](./AGENTS.md) for the fuller set of engineering
+principles and quality expectations this project follows.
+
+## Contributing
+
+Contributions are welcome. Please read [`AGENTS.md`](./AGENTS.md) for the
+project's engineering principles before opening a pull request, and see
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for the contribution workflow.
+
+## Security
+
+See [`SECURITY.md`](./SECURITY.md) for how to report a vulnerability.
+
+## License
+
+Licensed under the [MIT License](./LICENSE).
+
+`pybc365` is an independent open-source project and is not affiliated
+with or endorsed by Microsoft.

pybc365-0.1.0/pyproject.toml

@@ -0,0 +1,184 @@
+[project]
+name = "pybc365"
+version = "0.1.0"
+description = "A modern, fully typed Python client for Microsoft Dynamics 365 Business Central."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "business-central",
+    "dynamics-365",
+    "microsoft-dynamics",
+    "erp",
+    "api",
+    "odata",
+    "python",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.28.1"]
+
+[[project.authors]]
+name = "Akshay Prabhu"
+email = "akshay.prabhu@konspec.com"
+
+[project.urls]
+Homepage = "https://github.com/konfpa/pybc365"
+Repository = "https://github.com/konfpa/pybc365"
+Issues = "https://github.com/konfpa/pybc365/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.6,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx-ntlm>=1.4.0",
+    "mypy>=2.3.1",
+    "prek>=0.5.2",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.6",
+]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src"]
+preview = true
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "C4",
+    "SIM",
+    "RET",
+    "PTH",
+    "ANN",
+    "BLE",
+    "EM",
+    "TRY",
+    "RSE",
+    "T10",
+    "PT",
+    "ARG",
+    "TID",
+    "ISC",
+    "PIE",
+    "TC",
+    "ERA",
+    "C90",
+    "D",
+    "DOC",
+    "A",
+    "S",
+    "FBT",
+    "DTZ",
+    "LOG",
+    "G",
+    "INP",
+    "SLF",
+    "SLOT",
+    "PL",
+    "PERF",
+    "FURB",
+    "PGH",
+    "EXE",
+    "ICN",
+    "PYI",
+    "ASYNC",
+    "T20",
+    "YTT",
+    "INT",
+    "FLY",
+    "RUF",
+    "multi-line-summary-second-line",
+]
+ignore = [
+    "single-line-implicit-string-concatenation",
+    "raise-vanilla-args",
+    "docstring-extraneous-exception",
+    "multi-line-summary-first-line",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/*.py" = ["implicit-namespace-package"]
+"tests/**/*.py" = [
+    "ARG",
+    "assert",
+    "implicit-namespace-package",
+    "private-member-access",
+    "magic-value-comparison",
+    "import-private-name",
+    "import-outside-top-level",
+    "compare-to-empty-string",
+    "float-equality-comparison",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pybc365"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pylint]
+max-args = 8
+
+[tool.ruff.format]
+docstring-code-format = true
+exclude = ["*.md"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unreachable = true
+enable_error_code = [
+    "ignore-without-code",
+    "redundant-expr",
+    "possibly-undefined",
+]
+
+[[tool.mypy.overrides]]
+module = ["httpx_ntlm.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = [
+    "--cov=pybc365",
+    "--cov-report=term-missing",
+    "--cov-fail-under=95",
+    "-m",
+    "not live",
+]
+testpaths = ["tests"]
+markers = ["live: reads a real Business Central instance. Run with -m live."]
+
+[tool.coverage.run]
+source = ["pybc365"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+]