publish-py#

Introduction#

Generates a Python 3.11-or-newer package for every item and composite type in a COGS model. By default it uses dependency-free dataclasses; --flavor pydantic generates Pydantic v2 BaseModel classes instead. Both flavors read and write the same COGS JSON and XML instance formats.

Command Line Arguments#

Required inputs must be specified in this order:

  • [CogsLocation] is the model directory.

  • [TargetLocation] is the directory in which the package is created.

Command Line Flags#

  • -?|-h|--help displays command help.

  • -o|--overwrite replaces an existing target directory.

  • -n|--namespace overrides the XML namespace from model settings.

  • --flavor python|pydantic selects dependency-free Python (the default) or Pydantic v2. Values are case-insensitive; invalid values are usage errors.

Command Line Usage#

cogs publish-py [--overwrite] [--namespace URI] [--flavor python|pydantic] CogsLocation TargetLocation

For example:

cogs publish-py --overwrite MyModel generated/python
cogs publish-py --flavor pydantic --overwrite MyModel generated/python-pydantic

The model Slug is normalized into a Python import package name and a distribution name. A canonical SemVer alpha, beta, or rc release maps directly to PEP 440. Other valid SemVer prereleases receive a stable PEP-440 approximation and retain the original SemVer in generated COGS metadata. The command emits source-located warning PUB3101 whenever that approximation is used.

Generated Files#

The target contains pyproject.toml and a package directory containing model.py, __init__.py, and py.typed. Topics, articles, and other documentation-only metadata are not generated as runtime classes. The Pydantic flavor declares pydantic>=2.12,<3 in pyproject.toml. Generation requires neither Python nor Pydantic to be installed. The two flavors have the same package name and are alternative implementations, not packages to install together in one environment.

See Python Generation for naming, type mappings, and serialization behavior.