Editing Development/Packaging (section)

= 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]]