pycartosym 0.2.0__tar.gz

pycartosym-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxime Collombin
+
+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.

pycartosym-0.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pycartosym
+Version: 0.2.0
+Summary: Lossless transcoding between CartoSym CSS and other encodings for OGC Style & Symbology
+Author-email: Maxime Collombin <maxime.collombin@netplus.ch>
+License: MIT License
+        
+        Copyright (c) 2026 Maxime Collombin
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/maxcollombin/pycartosym
+Project-URL: Documentation, https://github.com/maxcollombin/pycartosym/blob/main/README.md
+Project-URL: Repository, https://github.com/maxcollombin/pycartosym.git
+Project-URL: Issues, https://github.com/maxcollombin/pycartosym/issues
+Keywords: gis,cartography,symbology,ogc,sld,cartosym
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: antlr4-python3-runtime>=4.13.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: jsonschema>=4.0.0
+Provides-Extra: dev
+Requires-Dist: antlr4-tools>=0.2.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: xmlschema>=3.0; extra == "dev"
+Provides-Extra: sld
+Requires-Dist: lxml>=4.9.0; extra == "sld"
+Provides-Extra: maplibre
+Provides-Extra: cql2
+Requires-Dist: pygeofilter>=0.2.0; extra == "cql2"
+Provides-Extra: all
+Requires-Dist: pycartosym[cql2,dev,maplibre,sld]; extra == "all"
+Dynamic: license-file
+
+# pycartosym
+
+[![CI](https://github.com/maxcollombin/pycartosym/actions/workflows/ci.yml/badge.svg)](https://github.com/maxcollombin/pycartosym/actions/workflows/ci.yml)
+
+A Python package for lossless transcoding between [CartoSym CSS](https://github.com/opengeospatial/styles-and-symbology) (`.cscss`) and other encodings of the OGC Style & Symbology conceptual model (CS-JSON, SLD/SE), plus MapLibre Style as a practical interoperability target.
+
+## Supported Formats
+
+CartoSym-CSS (`.cscss`) and CS-JSON (`.cs.json`) are the two OGC Style &
+Symbology encodings this package reads and writes losslessly. SLD/SE
+(`.sld`, 1.1.0 and 1.0.0, including SLD 1.0.0 with GeoServer
+`<VendorOption>` pass-through) is also OGC. MapLibre Style (`.json`) is
+the MapLibre/Mapbox de facto spec, not OGC, supported as a practical
+interoperability target. All are read and written.
+
+Each codec is covered for the constructs the target format actually
+expresses (a symbolizer or property with no equivalent on the other side
+raises rather than silently dropping data).
+
+## Installation
+
+### From PyPI (Coming Soon)
+
+```bash
+pip install pycartosym
+```
+
+### From Source
+
+```bash
+git clone https://github.com/maxcollombin/pycartosym.git
+cd pycartosym
+uv sync --all-extras
+```
+
+The generated ANTLR lexer/parser are already committed under
+`src/pycartosym/grammar/generated/`, so no separate grammar build
+step is needed. Prefix commands with `uv run`, or activate the
+project's `.venv` with `source .venv/bin/activate`.
+
+## Usage
+
+```bash
+# Format auto-detected from the file extensions where that's unambiguous
+cartosym <input-file> -o <output-file>
+
+# Explicit target format (needed for the SLD dialects and MapLibre,
+# since a plain .sld/.json extension can't disambiguate those)
+cartosym --to-format <sld|sld:1.0.0|sld:geoserver|maplibre|cscss|csjson> <input-file> -o <output-file>
+
+# Display structure info for a CSCSS file, without converting it
+cartosym parse <input-file>
+
+# Validate a .cscss or .cs.json file against the grammar/JSON schema
+cartosym validate <input-file>
+
+# Full option and format reference
+cartosym --help
+```
+
+A few concrete conversions, using the files under [`examples/`](examples/)
+(`examples/sld/` for SLD/SE):
+
+```bash
+cartosym examples/0-basic.cscss -o out.cs.json
+cartosym examples/13-vector-point-circle.cscss --to-format sld -o out.sld
+cartosym examples/sld/1-polygon-fill-stroke.sld --to-format maplibre -o out.json
+```
+
+## Python API
+
+Most users work through the `cartosym` CLI above. The `cql2` submodule also
+exposes CQL2 (the OGC 21-065r2 query-expression sublanguage that
+CartoSym-CSS embeds in `[ filter ]` selectors and CS-JSON encodes as
+`{"op": …, "args": …}`) as a stable, importable API:
+
+```python
+from pycartosym import cql2
+
+# CQL2-Text -> expression model
+expr = cql2.parse_text("population > 1000")
+
+# Expression model -> CQL2-JSON
+cql2.to_cql2_json(expr)
+# {'op': '>', 'args': [{'property': 'population'}, 1000]}
+
+# CQL2-JSON selector dict -> CartoSym-CSS filter text
+cql2.to_cql2_text({
+    "op": "and",
+    "args": [
+        {"op": "=", "args": [{"property": "a"}, 1]},
+        {"op": "like", "args": [{"property": "b"}, "x%"]},
+    ],
+})
+# "a = 1 and b like 'x%'"
+
+# Operator/function vocabulary, derived from the CQL2 Pydantic models
+cql2.vocab.SPATIAL_RELATE                       # 's_relate'
+"s_intersects" in cql2.vocab.KNOWN_CQL2_CALLS   # True
+```
+
+`cql2.parse_tree` is a lower-level entry point for converting an
+already-parsed ANTLR `expression` context (as produced while walking the
+CartoSym-CSS grammar) — most callers want `parse_text`.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+```
+
+## License
+
+See [LICENSE](LICENSE).

pycartosym-0.2.0/README.md

@@ -0,0 +1,115 @@
+# pycartosym
+
+[![CI](https://github.com/maxcollombin/pycartosym/actions/workflows/ci.yml/badge.svg)](https://github.com/maxcollombin/pycartosym/actions/workflows/ci.yml)
+
+A Python package for lossless transcoding between [CartoSym CSS](https://github.com/opengeospatial/styles-and-symbology) (`.cscss`) and other encodings of the OGC Style & Symbology conceptual model (CS-JSON, SLD/SE), plus MapLibre Style as a practical interoperability target.
+
+## Supported Formats
+
+CartoSym-CSS (`.cscss`) and CS-JSON (`.cs.json`) are the two OGC Style &
+Symbology encodings this package reads and writes losslessly. SLD/SE
+(`.sld`, 1.1.0 and 1.0.0, including SLD 1.0.0 with GeoServer
+`<VendorOption>` pass-through) is also OGC. MapLibre Style (`.json`) is
+the MapLibre/Mapbox de facto spec, not OGC, supported as a practical
+interoperability target. All are read and written.
+
+Each codec is covered for the constructs the target format actually
+expresses (a symbolizer or property with no equivalent on the other side
+raises rather than silently dropping data).
+
+## Installation
+
+### From PyPI (Coming Soon)
+
+```bash
+pip install pycartosym
+```
+
+### From Source
+
+```bash
+git clone https://github.com/maxcollombin/pycartosym.git
+cd pycartosym
+uv sync --all-extras
+```
+
+The generated ANTLR lexer/parser are already committed under
+`src/pycartosym/grammar/generated/`, so no separate grammar build
+step is needed. Prefix commands with `uv run`, or activate the
+project's `.venv` with `source .venv/bin/activate`.
+
+## Usage
+
+```bash
+# Format auto-detected from the file extensions where that's unambiguous
+cartosym <input-file> -o <output-file>
+
+# Explicit target format (needed for the SLD dialects and MapLibre,
+# since a plain .sld/.json extension can't disambiguate those)
+cartosym --to-format <sld|sld:1.0.0|sld:geoserver|maplibre|cscss|csjson> <input-file> -o <output-file>
+
+# Display structure info for a CSCSS file, without converting it
+cartosym parse <input-file>
+
+# Validate a .cscss or .cs.json file against the grammar/JSON schema
+cartosym validate <input-file>
+
+# Full option and format reference
+cartosym --help
+```
+
+A few concrete conversions, using the files under [`examples/`](examples/)
+(`examples/sld/` for SLD/SE):
+
+```bash
+cartosym examples/0-basic.cscss -o out.cs.json
+cartosym examples/13-vector-point-circle.cscss --to-format sld -o out.sld
+cartosym examples/sld/1-polygon-fill-stroke.sld --to-format maplibre -o out.json
+```
+
+## Python API
+
+Most users work through the `cartosym` CLI above. The `cql2` submodule also
+exposes CQL2 (the OGC 21-065r2 query-expression sublanguage that
+CartoSym-CSS embeds in `[ filter ]` selectors and CS-JSON encodes as
+`{"op": …, "args": …}`) as a stable, importable API:
+
+```python
+from pycartosym import cql2
+
+# CQL2-Text -> expression model
+expr = cql2.parse_text("population > 1000")
+
+# Expression model -> CQL2-JSON
+cql2.to_cql2_json(expr)
+# {'op': '>', 'args': [{'property': 'population'}, 1000]}
+
+# CQL2-JSON selector dict -> CartoSym-CSS filter text
+cql2.to_cql2_text({
+    "op": "and",
+    "args": [
+        {"op": "=", "args": [{"property": "a"}, 1]},
+        {"op": "like", "args": [{"property": "b"}, "x%"]},
+    ],
+})
+# "a = 1 and b like 'x%'"
+
+# Operator/function vocabulary, derived from the CQL2 Pydantic models
+cql2.vocab.SPATIAL_RELATE                       # 's_relate'
+"s_intersects" in cql2.vocab.KNOWN_CQL2_CALLS   # True
+```
+
+`cql2.parse_tree` is a lower-level entry point for converting an
+already-parsed ANTLR `expression` context (as produced while walking the
+CartoSym-CSS grammar) — most callers want `parse_text`.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+```
+
+## License
+
+See [LICENSE](LICENSE).

pycartosym-0.2.0/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pycartosym"
+version = "0.2.0"
+authors = [
+    {name = "Maxime Collombin", email = "maxime.collombin@netplus.ch"},
+]
+description = "Lossless transcoding between CartoSym CSS and other encodings for OGC Style & Symbology"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+keywords = ["gis", "cartography", "symbology", "ogc", "sld", "cartosym"]
+dependencies = [
+    "antlr4-python3-runtime>=4.13.0",
+    "pydantic>=2.0.0",
+    "jsonschema>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "antlr4-tools>=0.2.0",
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black",
+    "ruff>=0.6",
+    "mypy",
+    "xmlschema>=3.0",
+]
+sld = [
+    "lxml>=4.9.0",
+]
+maplibre = []
+cql2 = [
+    "pygeofilter>=0.2.0",
+]
+all = [
+    "pycartosym[dev,sld,cql2,maplibre]",
+]
+
+[project.urls]
+Homepage = "https://github.com/maxcollombin/pycartosym"
+Documentation = "https://github.com/maxcollombin/pycartosym/blob/main/README.md"
+Repository = "https://github.com/maxcollombin/pycartosym.git"
+Issues = "https://github.com/maxcollombin/pycartosym/issues"
+
+[project.scripts]
+cartosym = "pycartosym.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pycartosym = ["*.md", "schemas/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+filterwarnings = [
+    "ignore::DeprecationWarning:pydantic.*",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py310', 'py311', 'py312', 'py313', 'py314']
+extend-exclude = 'src/pycartosym/grammar/generated'
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+extend-exclude = ["src/pycartosym/grammar/generated"]
+
+[tool.ruff.lint]
+# E/F/W: flake8 parity. I: isort parity. UP: pyupgrade (safe on the
+# >=3.10 floor — PEP 604/585 syntax). FIX/TD: no stray TODO/FIXME/HACK
+# left in the tree — a known gap raises NotImplementedError with an inline
+# reason instead. D: pydocstyle (google convention); the undocumented-*
+# rules, D205, and D400/D401/D403/D415 (summary-line punctuation/mood/
+# case) are enforced in `src/` only (see per-file-ignores) — fixed by a
+# manual pass, not an autofix, since a naive one mangles identifiers like
+# `stylingRuleName`.
+# T20: no print() (CLAUDE.md rule — use logging; the CLI itself uses
+# sys.stdout.write/sys.stderr.write for genuine user-facing output,
+# not print()). ERA (commented-out code) is a separate follow-up.
+select = ["E", "F", "W", "I", "UP", "FIX", "TD", "D", "T20"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# A test's name and body document what it checks; docstring content and
+# summary-line layout carry little there. T201: golden-snapshot drift
+# diagnostics (test_expression_parser_tree.py) intentionally print to
+# stdout for a human reading pytest output — not a logging substitute.
+"tests/**" = [
+    "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107", "D205",
+    "D400", "D401", "D403", "D415", "T201",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pycartosym"]
+
+[tool.mypy]
+python_version = "3.10"
+plugins = ["pydantic.mypy"]
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+exclude = ["^src/pycartosym/grammar/generated/"]

pycartosym-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pycartosym-0.2.0/src/pycartosym/__init__.py

@@ -0,0 +1,38 @@
+"""Lossless transcoding between CartoSym-CSS, CS-JSON and other encodings.
+
+This package provides tools for converting between CartoSym CSS, CartoSym
+JSON format, and other cartographic symbology encodings like SLD (Styled
+Layer Descriptor) and MapLibre GL Style.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Single source of truth: pyproject.toml's [project] version, read back
+    # from the installed distribution's metadata — no hardcoded literal to
+    # drift out of sync with it.
+    __version__ = version("pycartosym")
+except PackageNotFoundError:
+    # Not installed (e.g. run from a source checkout without `uv sync`).
+    __version__ = "0.0.0+unknown"
+
+__author__ = "Maxime Collombin"
+__email__ = "maxime.collombin@netplus.ch"
+
+# Codec registry (lazy — sub-codecs register on first import of .codecs)
+from .codecs import detect_codec, get_codec, list_codecs  # noqa: F401
+from .converter import Converter
+from .exceptions import CartoSymError, CartoSymSyntaxError
+from .parser import CartoSymParser
+
+__all__ = [
+    "CartoSymParser",
+    "Converter",
+    "CartoSymError",
+    "CartoSymSyntaxError",
+    "get_codec",
+    "detect_codec",
+    "list_codecs",
+]

pycartosym-0.2.0/src/pycartosym/ast.py

@@ -0,0 +1,160 @@
+"""Abstract Syntax Tree (AST) classes for CartoSym CSS.
+
+This module contains the data structures representing parsed CartoSym CSS.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Variable:
+    """Variable definition in CartoSym CSS AST."""
+
+    name: str
+    value: Any
+    type: str | None = None
+
+
+@dataclass
+class StyleSheet:
+    """Root node of a CartoSym CSS stylesheet."""
+
+    metadata: list[Metadata] = field(default_factory=list)
+    styling_rules: StylingRuleList | None = None
+    variables: list[Variable] = field(default_factory=list)
+
+
+@dataclass
+class Metadata:
+    """Metadata entry in a stylesheet."""
+
+    key: str
+    value: str
+
+
+@dataclass
+class StylingRuleList:
+    """Collection of styling rules."""
+
+    rules: list[StylingRule]
+
+    def __post_init__(self):
+        """Default ``rules`` to an empty list when constructed with ``None``."""
+        if self.rules is None:
+            self.rules = []
+
+
+@dataclass
+class StylingRule:
+    """Individual styling rule with selector and properties."""
+
+    name: str | None = None
+    styling_rule_name: str | None = None  # explicit stylingRuleName from grammar
+    selector: Selector | None = None
+    # all selectors (for nested rules)
+    selectors: list = field(default_factory=list)
+    symbolizer: Symbolizer | None = None
+    nested_rules: list[StylingRule] = field(default_factory=list)
+    # all property assignments, for post-processing
+    property_assignments: list = field(default_factory=list)
+
+
+@dataclass
+class Selector:
+    """Selector for filtering features."""
+
+    expression: Expression | None = None
+
+
+@dataclass
+class Symbolizer:
+    """Symbolizer defining how features are rendered."""
+
+    # Basic properties
+    visibility: bool | None = None
+    opacity: float | None = None
+    z_order: int | None = None
+
+    # Vector symbolizers
+    fill: Fill | None = None
+    stroke: Stroke | None = None
+    marker: Marker | None = None
+    label: Label | None = None
+
+    # Coverage/Raster properties
+    single_channel: str | None = None  # e.g., "elevation"
+    singleChannel: str | None = None  # camelCase alternative
+    color_channels: Any | None = None  # RGB color channels
+    colorChannels: Any | None = None  # camelCase alternative
+    alpha_channel: Any | None = None  # Alpha channel
+    alphaChannel: Any | None = None  # camelCase alternative
+    color_map: Any | None = None  # Color mapping
+    colorMap: Any | None = None  # camelCase alternative
+    opacity_map: Any | None = None  # Opacity mapping
+    opacityMap: Any | None = None  # camelCase alternative
+    hill_shading: dict[str, Any] | None = None  # Hill shading config
+    hillShading: dict[str, Any] | None = None  # camelCase alternative
+
+
+@dataclass
+class Expression:
+    """Base class for expressions."""
+
+    pass
+
+
+@dataclass
+class PropertyAssignment:
+    """Assignment of a value to a property."""
+
+    property_name: str
+    value: Any
+
+
+@dataclass
+class PropertyAssignmentList:
+    """Collection of property assignments."""
+
+    assignments: list[PropertyAssignment]
+
+    def __post_init__(self):
+        """Default ``assignments`` to an empty list when constructed with ``None``."""
+        if self.assignments is None:
+            self.assignments = []
+
+
+@dataclass
+class Fill:
+    """Fill styling properties."""
+
+    color: str | None = None
+    opacity: float | None = None
+
+
+@dataclass
+class Stroke:
+    """Stroke styling properties."""
+
+    color: str | None = None
+    width: float | None = None
+    opacity: float | None = None
+
+
+@dataclass
+class Marker:
+    """Marker styling properties."""
+
+    elements: list | None = None
+
+
+@dataclass
+class Label:
+    """Label styling properties."""
+
+    elements: list | None = None
+    position: Any | None = None
+    opacity: float | None = None
+    placement: Any | None = None