tlc.core.helpers.project_layout

Static helpers for constructing URLs that conform to the 3LC project folder layout.

Module Contents

Classes

Class	Description
ProjectLayout	Static helpers for constructing URLs that conform to the 3LC project folder layout.

API

class ProjectLayout

Static helpers for constructing URLs that conform to the 3LC project folder layout.

All methods are static. When project_name or root_url are omitted the fallback chain is:

1. The active Run (via Session).

2. The configured project root URL and the fallback project name.

static create_unique_table_url(

url: Url | str,

require_writable: bool = False,

) → Url

Create a unique version of a table URL, optionally ensuring writability.

Calls Url.create_unique() to find a unique URL. If require_writable is True and the resulting URL is not writable, a fallback URL is created under the configured project root URL.

Parameters:

• url – The base URL to make unique.

• require_writable – If True, ensure the returned URL is writable. When the original location is not writable, the URL is relocated under the configured project root URL.

Returns:

A unique URL (writable if require_writable is True).

Raises:

ValueError – If require_writable is True but a writable URL cannot be created.

static dataset_url(

*,

dataset_name: str | None = None,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for a dataset directory.

Parameters:

• dataset_name – The dataset name. If not provided, the default dataset name is used.

• project_name – The project name.

• root_url – The root URL.

Returns:

A URL for the dataset directory.

static datasets_url(

*,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for the datasets subdirectory of a project.

Parameters:

• project_name – The project name.

• root_url – The root URL.

Returns:

A URL for the datasets directory.

static default_project_aliases_config_url(

*,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for the default-alias config file for a project.

Such a file is automatically read by any 3LC client and makes it possible to share a project without requiring extra configuration.

Parameters:

• project_name – The project name.

• root_url – The root URL.

Returns:

A URL for the default-alias config file.

static is_dataset_table_url(

url: Url | str,

) → bool

Check if url is a standard dataset table URL.

A canonical dataset table URL has the form …//datasets//tables/

.

Parameters:

url – The URL to check.

Returns:

True if the URL matches the canonical layout, False otherwise.

static is_project_dataset_url(

url: Url | str,

) → bool

Check if url is a standard project dataset URL.

A canonical project dataset URL has the form …//datasets/.

Parameters:

url – The URL to check.

Returns:

True if the URL matches the canonical layout, False otherwise.

static is_project_run_url(

url: Url | str,

) → bool

Check if url is a standard project run URL.

A canonical project run URL has the form …//runs/.

Parameters:

url – The URL to check.

Returns:

True if the URL matches the canonical layout, False otherwise.

static is_run_metrics_table_url(

url: Url | str,

) → bool

Check if url is a standard run metrics table URL.

A canonical run metrics table URL has the form …//runs//metrics_.

Parameters:

url – The URL to check.

Returns:

True if the URL matches the canonical layout, False otherwise.

static list_dataset_names(

*,

project_name: str | None = None,

root_url: Url | str | None = None,

) → list[str]

List all dataset names in a project.

Parameters:

• project_name – The project name.

• root_url – The root URL.

Returns:

A list of dataset names.

static list_project_names(

*,

root_url: Url | str | None = None,

include_scan_urls: bool = True,

) → list[str]

List all project names under the root URL and optional scan URLs.

Parameters:

• root_url – The root URL to scan. Defaults to the configured project root URL.

• include_scan_urls – If True, also scan URLs listed in Configuration.project_scan_urls.

Returns:

A deduplicated list of project names.

static list_run_names(

*,

project_name: str | None = None,

root_url: Url | str | None = None,

) → list[str]

List all run names in a project.

Parameters:

• project_name – The project name.

• root_url – The root URL.

Returns:

A list of run names.

static list_table_names(

*,

dataset_name: str | None = None,

project_name: str | None = None,

root_url: Url | str | None = None,

) → list[str]

List all table names in a dataset.

Parameters:

• dataset_name – The dataset name.

• project_name – The project name.

• root_url – The root URL.

Returns:

A list of table names.

static project_exists(

*,

project_name: str | None = None,

root_url: Url | str | None = None,

) → bool

Check whether the project directory exists.

Parameters:

• project_name – The project name.

• root_url – The root URL.

Returns:

True if the project directory exists, False otherwise.

static project_url(

*,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for a project conforming to the 3LC project folder layout.

When project_name or root_url are not provided, the fallback chain is:

1. The active Run (via Session).

2. The configured project root URL and the fallback project name.

Parameters:

• project_name – The project name. If not provided, the active or fallback project is used.

• root_url – The root URL. If not provided, the configured project root URL is used.

Returns:

A URL for the project directory.

static run_url(

*,

run_name: str | None = None,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for a run conforming to the 3LC project folder layout.

Parameters:

• run_name – The run name. If not provided, the default run name is used.

• project_name – The project name. If not provided, the active or fallback project is used.

• root_url – The root URL. If not provided, the configured project root URL is used.

Returns:

A URL for the run.

static run_url_parts(

url: Url | str,

) → tuple[str, str, str] | None

Extract the root, project name, and run name from a run URL.

This is the inverse of run_url(). Supports the following URL layouts:

• .../<project>/runs/<run>

• .../<project>/runs/<run>/<metrics_table>

Parameters:

url – The URL to parse.

Returns:

A (root, project_name, run_name) tuple, or None if the URL does not match.

static runs_url(

*,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for the runs subdirectory of a project.

Parameters:

• project_name – The project name.

• root_url – The root URL.

Returns:

A URL for the runs directory.

static table_url(

*,

table_name: str | None = None,

dataset_name: str | None = None,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for a table conforming to the 3LC project folder layout.

Parameters:

• table_name – The table name. If not provided, the default table name is used.

• dataset_name – The dataset name. If not provided, the default dataset name is used.

• project_name – The project name. If not provided, the active or fallback project is used.

• root_url – The root URL. If not provided, the configured project root URL is used.

Returns:

A URL for the table.

static table_url_parts(

url: Url | str,

) → tuple[str, str, str, str] | None

Extract the root, project name, dataset name, and table name from a table URL.

This is the inverse of table_url(). Supports the following URL layouts:

• .../<project>/datasets/<dataset>/tables/<table>

• .../<project>/datasets/<dataset>/tables/<table>/<sub_table>/...

Parameters:

url – The URL to parse.

Returns:

A (root, project_name, dataset_name, table_name) tuple, or None if the URL does not match.

static tables_url(

*,

dataset_name: str | None = None,

project_name: str | None = None,

root_url: Url | str | None = None,

) → Url

Create a URL for the tables subdirectory of a dataset.

Parameters:

• dataset_name – The dataset name.

• project_name – The project name.

• root_url – The root URL.

Returns:

A URL for the tables directory.

On this page

• tlc.core.helpers.project_layout
  • Module Contents
    • Classes
    • API
      • ProjectLayout
        • ProjectLayout.create_unique_table_url()
        • ProjectLayout.dataset_url()
        • ProjectLayout.datasets_url()
        • ProjectLayout.default_project_aliases_config_url()
        • ProjectLayout.is_dataset_table_url()
        • ProjectLayout.is_project_dataset_url()
        • ProjectLayout.is_project_run_url()
        • ProjectLayout.is_run_metrics_table_url()
        • ProjectLayout.list_dataset_names()
        • ProjectLayout.list_project_names()
        • ProjectLayout.list_run_names()
        • ProjectLayout.list_table_names()
        • ProjectLayout.project_exists()
        • ProjectLayout.project_url()
        • ProjectLayout.run_url()
        • ProjectLayout.run_url_parts()
        • ProjectLayout.runs_url()
        • ProjectLayout.table_url()
        • ProjectLayout.table_url_parts()
        • ProjectLayout.tables_url()

We use cookies to improve 3LC’s site. Some cookies are necessary for our website and services to function properly. Other cookies are optional and help personalize your experience, including advertising and analytics. You can consent to all cookies, decline all optional cookies, or manage optional cookies. Without a selection, our default cookie settings will apply. You can change your preferences at any time. To learn more, check out our Cookie Policy.

Accept Decline