Nicolas: Create Packaging conventions page from coding-conventions/PACKAGING.md (via create-page on MediaWiki MCP Server)

2026-04-23T02:05:32Z

Create Packaging conventions page from coding-conventions/PACKAGING.md (via create-page on MediaWiki MCP Server)

New page

= Packaging Conventions =

All duralex-* packages follow these conventions for consistent packaging, installation, and namespace management.

== Naming ==

{| class="wikitable"
! Layer !! Convention !! Example
|-
| Brand || Dura Lex (always two words) || —
|-
| Domain || <code>dura-lex.*</code> (hyphenated) || <code>dura-lex.org</code>
|-
| GitHub org || <code>duralex</code> || <code>github.com/duralex/</code>
|-
| PyPI package || <code>duralex-{name}</code> (hyphenated) || <code>duralex-fr</code>, <code>duralex-mcp</code>
|-
| Python import || <code>duralex.{name}</code> (dotted) || <code>from duralex.corpus import ...</code>
|-
| Exception || The core package is just <code>duralex</code> on PyPI || <code>pip install duralex</code>
|}

== Repository structure (6 repos) ==

<pre>
~/duralex/
├── duralex/ # PyPI: duralex (core + corpus + specs)
│ ├── pyproject.toml
│ ├── src/duralex/
│ │ ├── corpus/ # DocumentStore, FTS, TagQuery
│ │ ├── temporal/ # versioning, temporal types
│ │ ├── data/ # citation types, text utils
│ │ ├── annotations/ # annotation framework
│ │ ├── concepts/ # concept definitions
│ │ ├── errors.py # DuralexError base
│ │ ├── database.py # DSN builder
│ │ ├── logging.py # JSON/console logging
│ │ ├── middleware.py # ASGI middleware
│ │ └── retry.py # exponential backoff
│ ├── tests/
│ ├── sql/ # corpus DDL
│ ├── spec/ # authoritative specifications
│ ├── coding-conventions/ # this directory
│ ├── design-decisions/ # ADRs
│ ├── research/ # investigation logs
│ └── issues/ # issue tracker
│
├── duralex-jurisdictions/ # monorepo, two PyPI packages
│ ├── duralex-fr/ # PyPI: duralex-fr
│ │ ├── pyproject.toml
│ │ ├── src/duralex/fr/
│ │ └── tests/
│ └── duralex-eu/ # PyPI: duralex-eu
│ ├── pyproject.toml
│ ├── src/duralex/eu/
│ └── tests/
│
├── duralex-ingest/ # monorepo, three PyPI packages
│ ├── duralex-ingest/ # PyPI: duralex-ingest
│ │ ├── pyproject.toml
│ │ ├── src/duralex/ingest/ # NO __init__.py (namespace)
│ │ └── tests/
│ ├── duralex-ingest-fr/ # PyPI: duralex-ingest-fr
│ │ ├── pyproject.toml
│ │ ├── src/duralex/ingest/fr/
│ │ └── tests/
│ └── duralex-ingest-eu/ # PyPI: duralex-ingest-eu
│ ├── pyproject.toml
│ ├── src/duralex/ingest/eu/
│ └── tests/
│
├── duralex-mcp/ # PyPI: duralex-mcp (+ Docker infra)
│ ├── pyproject.toml
│ ├── src/duralex/mcp/
│ ├── tests/
│ ├── Dockerfile
│ ├── docker-compose.dev.yml
│ ├── docker-compose.prod.yml
│ └── Caddyfile
│
├── duralex-portal/ # PyPI: duralex-portal
│ ├── pyproject.toml
│ ├── src/duralex/portal/
│ └── tests/
│
└── duralex-feedback/ # standalone, not distributed
├── server.py
├── Dockerfile
└── docker-compose.yml
</pre>

== src layout with namespace packages ==

Every package uses the '''src layout''' with implicit namespace packages (PEP 420).

The critical rule: '''no <code>__init__.py</code> in namespace directories'''. Only leaf packages have <code>__init__.py</code>.

<pre>
duralex-fr/
├── pyproject.toml
├── src/
│ └── duralex/ # NO __init__.py (namespace)
│ └── fr/ # NO __init__.py (namespace)
│ ├── mcp/
│ │ ├── __init__.py # leaf package
│ │ └── ...
│ ├── refs/
│ │ ├── __init__.py
│ │ └── ...
│ └── courts/
│ ├── __init__.py
│ └── ...
└── tests/
</pre>

=== Special case: duralex-ingest namespace ===

The <code>duralex.ingest</code> namespace is shared across three packages. The base <code>duralex-ingest</code> package must NOT have <code>__init__.py</code> at <code>src/duralex/ingest/</code> — otherwise Python blocks namespace discovery of <code>duralex.ingest.fr</code> and <code>duralex.ingest.eu</code> from sibling packages.

<pre>
duralex-ingest/duralex-ingest/src/duralex/ingest/ # NO __init__.py
duralex-ingest/duralex-ingest/src/duralex/ingest/database/__init__.py # leaf
duralex-ingest/duralex-ingest-fr/src/duralex/ingest/fr/__init__.py # leaf
duralex-ingest/duralex-ingest-eu/src/duralex/ingest/eu/__init__.py # leaf
</pre>

== pyproject.toml template ==

<syntaxhighlight lang="toml">
[build-system]
requires = ["setuptools>=69.0"]
build-backend = "setuptools.build_meta"

[project]
name = "duralex-fr"
version = "0.1.0"
description = "France: legal reference resolver, court hierarchy, and validation for the Dura Lex ecosystem"
requires-python = ">=3.12"
license = "MIT"
authors = [{ name = "Nicolas Baldeck" }]
keywords = ["legal", "open-data", "france"]

dependencies = [
"duralex>=0.1.0",
]

[project.optional-dependencies]
dev = [
"pytest>=8.2",
"ruff>=0.15",
"mypy>=1.15",
]

[tool.setuptools.packages.find]
where = ["src"]
include = ["duralex.fr*"]

[tool.ruff]
line-length = 120
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "W", "I", "UP", "B", "SIM", "TCH", "RUF", "PTH"]

[tool.ruff.format]
quote-style = "double"

[tool.mypy]
python_version = "3.12"
strict = true
namespace_packages = true
explicit_package_bases = true
mypy_path = ["src", "../../duralex/src"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = ["--strict-config", "--strict-markers", "--import-mode=importlib", "-m not slow and not integration"]
xfail_strict = true
consider_namespace_packages = true
filterwarnings = ["error"]
markers = [
"slow: tests with extended runtime",
"integration: requires PostgreSQL (testcontainers)",
]
</syntaxhighlight>

== Editable development installs ==

Install all packages in editable mode from the repo root:

<syntaxhighlight lang="bash">
cd ~/duralex
pip install -e "./duralex[dev,pg]"
pip install -e "./duralex-jurisdictions/duralex-fr[dev,db]"
pip install -e "./duralex-jurisdictions/duralex-eu[dev]"
pip install -e "./duralex-ingest/duralex-ingest[dev]"
pip install -e "./duralex-ingest/duralex-ingest-fr[dev]"
pip install -e "./duralex-ingest/duralex-ingest-eu[dev]"
pip install -e "./duralex-mcp[dev]"
pip install -e "./duralex-portal[dev]"
</syntaxhighlight>

If namespace resolution breaks between sibling packages:

<syntaxhighlight lang="bash">
pip install -e ".[dev]" --config-settings editable_mode=compat
</syntaxhighlight>

== Version policy ==

All packages start at <code>0.1.0</code>. Packages are versioned independently. A major version bump in <code>duralex</code> triggers compatibility review in all downstream packages.

== Brand vs. code ==

The brand is always written '''Dura Lex''' (two words). Code identifiers use <code>duralex</code> (one word, no space) because Python and PyPI do not allow spaces. Never write "Duralex" — it is either "Dura Lex" (prose) or <code>duralex</code> (code).

[[Category:Development]]

Development/Packaging - Revision history

Nicolas: Create Packaging conventions page from coding-conventions/PACKAGING.md (via create-page on MediaWiki MCP Server)