esrf-pathlib
============

The :ref:`ESRFPath<esrfpath-api>` class extends Python's built-in `pathlib.Path`_,
adding support for ESRF-specific path schemas.

When an :class:`ESRFPath` instance matches a *path template* from recognized ESRF *schema*,
additional attributes are exposed such as `beamline` and `processed_data_path`

.. code-block:: python-console

    >>> from esrf_pathlib import ESRFPath
    >>> 
    >>> path = ESRFPath("/data/visitor/ma1234/id00/20250509/RAW_DATA/sample/sample_dataset")
    >>> path
    <ESRFPath '/data/visitor/ma1234/id00/20250509/RAW_DATA/sample/sample_dataset' schema='esrf_v3' template='raw_dataset_path'>
    >>> print("Proposal:", path.proposal)
    Proposal: ma1234
    >>> print("Processed results:", path.processed_dataset_file)
    Processed results: /data/visitor/ma1234/id00/20250509/PROCESSED_DATA/sample/sample_dataset/sample_dataset.h5

By default all path templates from the latest ESRF schema are recognized with fallback to the previous version.

To change the default schema derive a class (``None`` denotes the latest version of a schema)

.. code-block:: python

    class TomoPath(ESRFPath, tomo=None, fallback_depth=1):
        pass

To enforce the schema without deriving a class

.. code-block:: python

    >>> path = ESRFPath.from_path("/data/visitor/ma1234/id00/20250509/raw/sample/sample_dataset", schema_name="esrf", schema_version=2)
    >>> path.processed_dataset_file
    <ESRFPath '/data/visitor/ma1234/id00/20250509/processed/sample/sample_dataset/sample_dataset.h5' schema='esrf_v2' template='processed_dataset_file'>

The ``ESRFPath`` object retains full compatibility with `pathlib.Path`_ and behaves as a standard path object:

.. code:: python-console

    >>> path.is_absolute()
    True
    >>> path.root
    '/'

ESRF-specific behavior is preserved when manipulating paths:

.. code:: python-console

    >>> path = ESRFPath("/data/visitor/ma1234/id00/20250509/PROCESSED_DATA")
    >>> new_path = path / "result.h5"
    >>> new_path
    <ESRFPath '/data/visitor/ma1234/id00/20250509/PROCESSED_DATA/result.h5' schema='esrf_v3' template='processed_data_path'
    >>> new_path.data_type
    <DataType.PROCESSED: 'processed'>

.. toctree::
   :hidden:

   reference

.. _pathlib.Path: https://docs.python.org/3/library/pathlib.html