api_endpoints

plantdb.client.api_endpoints Link

API Endpoints for PlantDB client.

This module provides helper functions to construct URL paths for the PlantDB REST API. Each function returns the endpoint string with optional prefix and performs basic sanitization of identifiers.

Key Features

Sanitizes and validates scan, fileset, and file names.
Supports optional URL prefixes for API versioning.
Generates paths for authentication, health checks, scans, images, and archives.

Usage Examples

from plantdb.client import api_endpoints api_endpoints.login(prefix='/api/v1') '/api/v1/login' api_endpoints.scan('plant1', prefix='/api/v1') '/api/v1/scans/plant1'

archive Link

archive(scan_id, **kwargs)

Return the URL path to the dataset archive endpoint.

Parameters:

Name	Type	Description	Default
`scan_id`	`str`	The name of the scan dataset to archive.	required

Returns:

Type	Description
`str`	The URL path to the dataset archive endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.archive('scan1')
'/archive/scan1'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def archive(scan_id: str, **kwargs) -> str:
    """Return the URL path to the dataset archive endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset to archive.

    Returns
    -------
    str
        The URL path to the dataset archive endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.archive('scan1')
    '/archive/scan1'
    """
    scan_id = sanitize_name(scan_id)
    return f"/archive/{scan_id}"

file Link

file(scan_id, fileset_id, file_id, **kwargs)

Return the URL path to the scan/fileset/file endpoint.

Parameters:

Name	Type	Description	Default
`scan_id`	`str`	The name of the scan dataset containing the file.	required
`fileset_id`	`str`	The name of the fileset containing the file.	required
`file_id`	`str`	The name of the file.	required

Returns:

Type	Description
`str`	The URL path to the file endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.file('real_plant','images','00000_rgb')
'/files/real_plant/images/00000_rgb'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def file(scan_id: str, fileset_id: str, file_id: str, **kwargs) -> str:
    """Return the URL path to the `scan/fileset/file` endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the file.
    fileset_id : str
        The name of the fileset containing the file.
    file_id : str
        The name of the file.

    Returns
    -------
    str
        The URL path to the file endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.file('real_plant','images','00000_rgb')
    '/files/real_plant/images/00000_rgb'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)
    file_id = sanitize_name(file_id)
    return f"/files/{scan_id}/{fileset_id}/{file_id}"

health Link

health(**kwargs)

Return the URL path to the health endpoint.

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the health endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.health(prefix='/api/v1')
'/api/v1/health'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def health(**kwargs) -> str:
    """Return the URL path to the health endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the health endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.health(prefix='/api/v1')
    '/api/v1/health'
    """
    return "/health"

image Link

image(scan_id, fileset_id, file_id, size, **kwargs)

Return the URL path to the image endpoint.

Parameters:

Name	Type	Description	Default
`scan_id`	`str`	The name of the scan dataset containing the image.	required
`fileset_id`	`str`	The name of the fileset containing the image.	required
`file_id`	`str`	The name of the image.	required
`size`	`str or int`	The size parameter of the image request.	required

Returns:

Type	Description
`str`	The URL path to the image endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.image('real_plant','images','00000_rgb', 'orig')
'/image/real_plant/images/00000_rgb?size=orig'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def image(scan_id: str, fileset_id: str, file_id: str, size: str, **kwargs) -> str:
    """Return the URL path to the image endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the image.
    fileset_id : str
        The name of the fileset containing the image.
    file_id : str
        The name of the image.
    size : str or int
        The size parameter of the image request.

    Returns
    -------
    str
        The URL path to the image endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.image('real_plant','images','00000_rgb', 'orig')
    '/image/real_plant/images/00000_rgb?size=orig'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)
    file_id = sanitize_name(file_id)
    return f"/image/{scan_id}/{fileset_id}/{file_id}?size={size}"

login(**kwargs)

Return the URL path to the login endpoint.

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the login endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.login(prefix='/api/v1')
'/api/v1/login'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def login(**kwargs) -> str:
    """Return the URL path to the login endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the login endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.login(prefix='/api/v1')
    '/api/v1/login'
    """
    return "/login"

logout Link

logout(**kwargs)

Return the URL path to the logout endpoint.

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the logout endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.logout(prefix='/api/v1')
'/api/v1/logout'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def logout(**kwargs) -> str:
    """Return the URL path to the logout endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the logout endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.logout(prefix='/api/v1')
    '/api/v1/logout'
    """
    return "/logout"

refresh Link

refresh(scan_id=None, **kwargs)

Return the URL path to the dataset archive endpoint.

Parameters:

Name	Type	Description	Default
`scan_id`	`str`	The name of the scan dataset to archive.	`None`

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the refresh endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.refresh(prefix='/api/v1')
'/api/v1/refresh'
>>> api_endpoints.refresh('scan1')
'/refresh?scan_id=scan1'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def refresh(scan_id: str = None, **kwargs) -> str:
    """Return the URL path to the dataset archive endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset to archive.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the refresh endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.refresh(prefix='/api/v1')
    '/api/v1/refresh'
    >>> api_endpoints.refresh('scan1')
    '/refresh?scan_id=scan1'
    """
    params = ""
    if scan_id:
        scan_id = sanitize_name(scan_id)
        params = f"?scan_id={scan_id}"
    return f"/refresh{params}"

register Link

register(**kwargs)

Return the URL path to the register endpoint.

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the register endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.register(prefix='/api/v1')
'/api/v1/register'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def register(**kwargs) -> str:
    """Return the URL path to the register endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the register endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.register(prefix='/api/v1')
    '/api/v1/register'
    """
    return "/register"

sanitize_name Link

sanitize_name(name)

Sanitizes and validates the provided name.

The function ensures that the input string adheres to predefined naming rules by:

stripping leading/trailing spaces,
isolating the last segment after splitting by slashes,
validating the name against an alphanumeric pattern with optional underscores (_), dashes (-), or periods (.).

Parameters:

Name	Type	Description	Default
`name`	`str`	The name to sanitize and validate.	required

Returns:

Type	Description
`str`	Sanitized name that conforms to the rules.

Raises:

Type	Description
`ValueError`	If the provided name contains invalid characters or does not meet the naming rules.

Source code in plantdb/client/api_endpoints.py

def sanitize_name(name):
    """Sanitizes and validates the provided name.

    The function ensures that the input string adheres to predefined naming rules by:

    - stripping leading/trailing spaces,
    - isolating the last segment after splitting by slashes,
    - validating the name against an alphanumeric pattern
      with optional underscores (`_`), dashes (`-`), or periods (`.`).

    Parameters
    ----------
    name : str
        The name to sanitize and validate.

    Returns
    -------
    str
        Sanitized name that conforms to the rules.

    Raises
    ------
    ValueError
        If the provided name contains invalid characters or does not meet the naming rules.
    """
    import re
    sanitized_name = name.strip()  # Remove leading/trailing spaces
    sanitized_name = sanitized_name.split('/')[-1]  # isolate the last segment after splitting by slashes
    # Validate against an alphanumeric pattern with optional underscores, dashes, or periods
    if not re.match(r"^[a-zA-Z0-9_.-]+$", sanitized_name):
        raise ValueError(
            f"Invalid name: '{name}'. Names must be alphanumeric and can include underscores, dashes, or periods.")
    return sanitized_name

scan Link

scan(scan_id, **kwargs)

Return the URL path to the scan endpoint.

Parameters:

Name	Type	Description	Default
`scan_id`	`str`	The name of the scan to access.	required

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the scan endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.scan('scan1')
'/scans/scan1'
>>> api_endpoints.scan('scan1', prefix='/api/v1')
'/api/v1/scans/scan1'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def scan(scan_id: str, **kwargs) -> str:
    """Return the URL path to the scan endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the scan endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.scan('scan1')
    '/scans/scan1'
    >>> api_endpoints.scan('scan1', prefix='/api/v1')
    '/api/v1/scans/scan1'
    """
    return f"/scans/{sanitize_name(scan_id)}"

scan_file Link

scan_file(scan_id, file_path, **kwargs)

Return the URL path to the scan/fileset/file endpoint.

Parameters:

Name	Type	Description	Default
`scan_id`	`str`	The name of the scan dataset containing the file.	required
`file_path`	`str`	The path to the file in the database.	required

Returns:

Type	Description
`str`	The URL path to the file endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.scan_file('real_plant','images/00000_rgb.jpg')
'/files/real_plant/images/00000_rgb.jpg'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def scan_file(scan_id: str, file_path: str, **kwargs) -> str:
    """Return the URL path to the `scan/fileset/file` endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the file.
    file_path : str
        The path to the file in the database.

    Returns
    -------
    str
        The URL path to the file endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.scan_file('real_plant','images/00000_rgb.jpg')
    '/files/real_plant/images/00000_rgb.jpg'
    """
    scan_id = sanitize_name(scan_id)
    return f"/files/{scan_id}/{file_path.lstrip('/')}"

scans Link

scans(**kwargs)

Return the URL path to the scans endpoint.

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the scans endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.scans(prefix='/api/v1')
'/api/v1/scans'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def scans(**kwargs) -> str:
    """Return the URL path to the scans endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the scans endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.scans(prefix='/api/v1')
    '/api/v1/scans'
    """
    return "/scans"

token_refresh Link

token_refresh(**kwargs)

Return the URL path to the token refresh endpoint.

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the token refresh endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.token_refresh(prefix='/api/v1')
'/api/v1/token-refresh'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def token_refresh(**kwargs) -> str:
    """Return the URL path to the token refresh endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the token refresh endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.token_refresh(prefix='/api/v1')
    '/api/v1/token-refresh'
    """
    return "/token-refresh"

token_validation Link

token_validation(**kwargs)

Return the URL path to the token validation endpoint.

Other Parameters:

Name	Type	Description
`prefix`	`str`	An optional prefix to prepend to the URL path.

Returns:

Type	Description
`str`	The URL path to the token validation endpoint.

Examples:

>>> from plantdb.client import api_endpoints
>>> api_endpoints.token_validation(prefix='/api/v1')
'/api/v1/token-validation'

Source code in plantdb/client/api_endpoints.py

@url_prefix
def token_validation(**kwargs) -> str:
    """Return the URL path to the token validation endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the token validation endpoint.

    Examples
    --------
    >>> from plantdb.client import api_endpoints
    >>> api_endpoints.token_validation(prefix='/api/v1')
    '/api/v1/token-validation'
    """
    return "/token-validation"

url_prefix Link

url_prefix(endpoint_path)

Wrap an endpoint path generator with an optional URL prefix.

Examples:

>>> def base_path(user_id):
...     return f"/users/{user_id}"
...
>>> prefixed = url_prefix(base_path)
>>> prefixed(42)
'/users/42'
>>> prefixed(42, prefix='api')
'/api/users/42'
>>> prefixed(42, prefix='/api/')
'/api/users/42'

Source code in plantdb/client/api_endpoints.py

def url_prefix(endpoint_path):
    """
    Wrap an endpoint path generator with an optional URL prefix.

    Examples
    --------
    >>> def base_path(user_id):
    ...     return f"/users/{user_id}"
    ...
    >>> prefixed = url_prefix(base_path)
    >>> prefixed(42)
    '/users/42'
    >>> prefixed(42, prefix='api')
    '/api/users/42'
    >>> prefixed(42, prefix='/api/')
    '/api/users/42'
    """

    def wrapper(*args, **kwargs):
        if "prefix" in kwargs and kwargs["prefix"]:
            prefix = kwargs["prefix"]
            prefix = '/' + prefix.lstrip('/').rstrip('/')
            return prefix + endpoint_path(*args, **kwargs)
        else:
            return endpoint_path(*args, **kwargs)

    return wrapper

api_endpoints

plantdb.client.api_endpoints Link

archive Link

file Link

health Link

image Link

login Link

logout Link

refresh Link

register Link

sanitize_name Link

scan Link

scan_file Link

scans Link

token_refresh Link

token_validation Link

url_prefix Link