pathbase 0.0.1__tar.gz → 0.1.0__tar.gz

pathbase-0.1.0/LICENSE

@@ -0,0 +1,12 @@
+pathbase
+
+Copyright (c) 2026, Ryan Galloway (ryan@rsgalloway.com)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    * Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pathbase-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.1
+Name: pathbase
+Version: 0.1.0
+Summary: Lightweight bidirectional filesystem path templates for Python.
+Author-email: Ryan Galloway <ryan@rsgalloway.com>
+License: BSD-3-Clause
+Keywords: filesystem,path,template,parsing,formatting,pipeline,vfx
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: flake8==7.1.1; extra == "dev"
+Requires-Dist: mccabe==0.7.0; extra == "dev"
+Requires-Dist: isort==5.13.2; extra == "dev"
+Requires-Dist: black==24.8.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# pathbase
+
+[![PyPI](https://img.shields.io/pypi/v/pathbase.svg?color=blue)](https://pypi.org/project/pathbase/)
+[![CI](https://github.com/rsgalloway/pathbase/actions/workflows/tests.yml/badge.svg)](https://github.com/rsgalloway/pathbase/actions/workflows/tests.yml)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+`pathbase` is a lightweight, dependency-free Python library for bidirectional
+filesystem path templates.
+
+It is being extracted from the path-template functionality in `envstack.path`
+into a focused standalone package that stays intentionally small.
+
+## Installation
+
+```bash
+pip install -U pathbase
+```
+
+## Quick Example
+
+Given a real filepath, `pathbase` can discover the matching template from
+environment-provided templates and extract the tokens:
+
+```bash
+export FILEPATH='{show}/{sequence}/{shot}/{step}/{task}_{descriptor}_v{version:03d}.{frame:04d}.{ext}'
+pathbase parse 'bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'
+```
+
+Expected output:
+
+```json
+{
+  "fields": {
+    "descriptor": "beauty",
+    "ext": "exr",
+    "frame": 1001,
+    "sequence": "seq001",
+    "shot": "shot010",
+    "show": "bigbuckbunny",
+    "step": "lighting",
+    "task": "render",
+    "version": 1
+  },
+  "template": "FILEPATH"
+}
+```
+
+The same flow also works well with envstack-managed templates. For example:
+
+```bash
+export ENVPATH=./examples/vfx
+pathbase parse \
+  '/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'
+```
+
+You can also work with templates directly from Python:
+
+```python
+from pathbase import Template
+
+template = Template(
+    "{show}/{sequence}/{shot}/{step}/"
+    "{task}_{descriptor}_v{version:03d}.{frame:04d}.{ext}"
+)
+
+path = template.format(
+    show="bigbuckbunny",
+    sequence="seq001",
+    shot="shot010",
+    step="lighting",
+    task="render",
+    descriptor="beauty",
+    version=1,
+    frame=1001,
+    ext="exr",
+)
+
+fields = template.parse(
+    "bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr"
+)
+```
+
+Pathbase supports:
+
+- `Template.format(...)` for path construction
+- `Template.parse(path)` for field extraction
+- automatic environment-based template discovery for CLI parsing and matching
+- typed numeric fields such as `{version:03d}` and `{value:.2f}`
+- repeated-field validation
+- mixed-separator parsing
+- embedded `$VAR` and `${VAR}` expansion from `os.environ` or an explicit mapping
+- `Template.from_env(...)` as a convenience for environment-provided templates
+
+Formatting output:
+
+```text
+bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr
+```
+
+Parsing output:
+
+```python
+{
+    "show": "bigbuckbunny",
+    "sequence": "seq001",
+    "shot": "shot010",
+    "step": "lighting",
+    "task": "render",
+    "descriptor": "beauty",
+    "version": 1,
+    "frame": 1001,
+    "ext": "exr",
+}
+```
+
+## CLI
+
+`pathbase` also includes a lightweight CLI:
+
+```bash
+pathbase format --template '{project}/{name}_v{version:03d}.txt' \
+  project=demo name=report version=1
+
+pathbase parse \
+  'demo/report_v001.txt'
+
+pathbase parse --template FILEPATH \
+  'demo/report_v001.txt'
+
+pathbase match 'demo/report.txt'
+```
+
+Additional documentation lives in [docs/README.md](docs/README.md):
+
+- [Examples](docs/examples.md)

pathbase-0.1.0/README.md

@@ -0,0 +1,135 @@
+# pathbase
+
+[![PyPI](https://img.shields.io/pypi/v/pathbase.svg?color=blue)](https://pypi.org/project/pathbase/)
+[![CI](https://github.com/rsgalloway/pathbase/actions/workflows/tests.yml/badge.svg)](https://github.com/rsgalloway/pathbase/actions/workflows/tests.yml)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+`pathbase` is a lightweight, dependency-free Python library for bidirectional
+filesystem path templates.
+
+It is being extracted from the path-template functionality in `envstack.path`
+into a focused standalone package that stays intentionally small.
+
+## Installation
+
+```bash
+pip install -U pathbase
+```
+
+## Quick Example
+
+Given a real filepath, `pathbase` can discover the matching template from
+environment-provided templates and extract the tokens:
+
+```bash
+export FILEPATH='{show}/{sequence}/{shot}/{step}/{task}_{descriptor}_v{version:03d}.{frame:04d}.{ext}'
+pathbase parse 'bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'
+```
+
+Expected output:
+
+```json
+{
+  "fields": {
+    "descriptor": "beauty",
+    "ext": "exr",
+    "frame": 1001,
+    "sequence": "seq001",
+    "shot": "shot010",
+    "show": "bigbuckbunny",
+    "step": "lighting",
+    "task": "render",
+    "version": 1
+  },
+  "template": "FILEPATH"
+}
+```
+
+The same flow also works well with envstack-managed templates. For example:
+
+```bash
+export ENVPATH=./examples/vfx
+pathbase parse \
+  '/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'
+```
+
+You can also work with templates directly from Python:
+
+```python
+from pathbase import Template
+
+template = Template(
+    "{show}/{sequence}/{shot}/{step}/"
+    "{task}_{descriptor}_v{version:03d}.{frame:04d}.{ext}"
+)
+
+path = template.format(
+    show="bigbuckbunny",
+    sequence="seq001",
+    shot="shot010",
+    step="lighting",
+    task="render",
+    descriptor="beauty",
+    version=1,
+    frame=1001,
+    ext="exr",
+)
+
+fields = template.parse(
+    "bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr"
+)
+```
+
+Pathbase supports:
+
+- `Template.format(...)` for path construction
+- `Template.parse(path)` for field extraction
+- automatic environment-based template discovery for CLI parsing and matching
+- typed numeric fields such as `{version:03d}` and `{value:.2f}`
+- repeated-field validation
+- mixed-separator parsing
+- embedded `$VAR` and `${VAR}` expansion from `os.environ` or an explicit mapping
+- `Template.from_env(...)` as a convenience for environment-provided templates
+
+Formatting output:
+
+```text
+bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr
+```
+
+Parsing output:
+
+```python
+{
+    "show": "bigbuckbunny",
+    "sequence": "seq001",
+    "shot": "shot010",
+    "step": "lighting",
+    "task": "render",
+    "descriptor": "beauty",
+    "version": 1,
+    "frame": 1001,
+    "ext": "exr",
+}
+```
+
+## CLI
+
+`pathbase` also includes a lightweight CLI:
+
+```bash
+pathbase format --template '{project}/{name}_v{version:03d}.txt' \
+  project=demo name=report version=1
+
+pathbase parse \
+  'demo/report_v001.txt'
+
+pathbase parse --template FILEPATH \
+  'demo/report_v001.txt'
+
+pathbase match 'demo/report.txt'
+```
+
+Additional documentation lives in [docs/README.md](docs/README.md):
+
+- [Examples](docs/examples.md)

pathbase-0.1.0/lib/pathbase/__init__.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python
+#
+# Copyright (c) 2026, Ryan Galloway (ryan@rsgalloway.com)
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#  - Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+#  - Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+#  - Neither the name of the software nor the names of its contributors
+#    may be used to endorse or promote products derived from this software
+#    without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+
+"""Lightweight bidirectional filesystem path templates."""
+
+try:
+    import envstack
+
+    envstack.init("pathbase")
+except ImportError:
+    pass
+
+from pathbase.exceptions import (
+    AmbiguousTemplateError,
+    FieldFormatError,
+    InvalidPathError,
+    InvalidTemplateError,
+    MissingFieldError,
+    PathbaseError,
+)
+from pathbase.template import Template, find_matching_templates, match_template
+
+__all__ = [
+    "AmbiguousTemplateError",
+    "FieldFormatError",
+    "InvalidPathError",
+    "InvalidTemplateError",
+    "MissingFieldError",
+    "PathbaseError",
+    "Template",
+    "find_matching_templates",
+    "match_template",
+    "__version__",
+]
+
+__version__ = "0.1.0"

pathbase-0.1.0/lib/pathbase/cli.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python
+#
+# Copyright (c) 2026, Ryan Galloway (ryan@rsgalloway.com)
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#  - Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+#  - Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+#  - Neither the name of the software nor the names of its contributors
+#    may be used to endorse or promote products derived from this software
+#    without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+
+"""Command-line tools for pathbase."""
+
+import argparse
+import json
+import sys
+from typing import Dict, List, Optional
+
+from pathbase import PathbaseError, Template, match_template
+
+
+def _parse_field_assignments(items: List[str]) -> Dict[str, str]:
+    """Parse key=value items into a field mapping."""
+    fields = {}
+    for item in items:
+        if "=" not in item:
+            raise ValueError("field assignments must use key=value syntax")
+        key, value = item.split("=", 1)
+        if not key:
+            raise ValueError("field names cannot be empty")
+        fields[key] = value
+    return fields
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level pathbase CLI parser."""
+    from pathbase import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="pathbase",
+        description="pathbase: bidirectional filesystem path templates",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="pathbase {0}".format(__version__),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>", required=True)
+
+    p_format = subparsers.add_parser("format", help="format a path from a template")
+    format_group = p_format.add_mutually_exclusive_group(required=True)
+    format_group.add_argument("--template", help="template string")
+    format_group.add_argument("--template-env", help="environment variable containing a template")
+    p_format.add_argument(
+        "fields",
+        nargs="*",
+        help="field assignments in key=value form",
+    )
+
+    p_parse = subparsers.add_parser("parse", help="parse a path using an environment template")
+    p_parse.add_argument(
+        "--template",
+        help="environment variable name containing the template to use",
+    )
+    p_parse.add_argument("path", help="path to parse")
+
+    p_match = subparsers.add_parser("match", help="find or test a matching template")
+    p_match.add_argument(
+        "--template",
+        help="environment variable name containing the template to use",
+    )
+    p_match.add_argument("path", help="path to test")
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Run the pathbase CLI."""
+    args = build_parser().parse_args(argv)
+
+    try:
+        if args.command == "format":
+            fields = _parse_field_assignments(args.fields)
+            if args.template_env:
+                template = Template.from_env(args.template_env)
+            else:
+                template = Template(args.template)
+            print(template.format(**fields))
+            return 0
+
+        if args.command == "parse":
+            if args.template:
+                template_name = args.template
+                template = Template.from_env(template_name)
+            else:
+                template_name, template = match_template(args.path)
+            result = {
+                "template": template_name,
+                "fields": template.parse(args.path),
+            }
+            print(json.dumps(result, indent=2, sort_keys=True))
+            return 0
+
+        if args.command == "match":
+            if args.template:
+                template = Template.from_env(args.template)
+                if template.matches(args.path):
+                    print(args.template)
+                    return 0
+                print("false")
+                return 1
+            template_name, _ = match_template(args.path)
+            print(template_name)
+            return 0
+
+    except (PathbaseError, ValueError) as err:
+        print(str(err), file=sys.stderr)
+        return 2
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pathbase-0.1.0/lib/pathbase/exceptions.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+#
+# Copyright (c) 2026, Ryan Galloway (ryan@rsgalloway.com)
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#  - Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+#  - Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+#  - Neither the name of the software nor the names of its contributors
+#    may be used to endorse or promote products derived from this software
+#    without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+
+"""Custom exceptions for pathbase."""
+
+
+class PathbaseError(Exception):
+    """Base exception for pathbase."""
+
+
+class InvalidTemplateError(PathbaseError):
+    """Raised when a template string is invalid."""
+
+
+class MissingFieldError(PathbaseError):
+    """Raised when required fields are missing during formatting."""
+
+
+class FieldFormatError(PathbaseError):
+    """Raised when a field value cannot be coerced to its declared type."""
+
+
+class InvalidPathError(PathbaseError):
+    """Raised when a path does not match a template."""
+
+
+class AmbiguousTemplateError(PathbaseError):
+    """Raised when more than one template matches a path."""