PathNamer#

class scikitplot.utils._path.PathNamer(root=PosixPath('scikitplot-artifacts'), default_prefix='file', default_ext='', by_day=False, add_secret=False, private=False, mkdir=True)[source]#

Generate portable, collision-resistant filenames and paths.

Parameters:

rootpathlib.Path, default=Path(“output”): Base directory where paths are created. “~” and env vars are expanded.
default_prefixstr, default=”file”: Default filename prefix (sanitized before use).
default_extstr, default=””: Default extension, with or without a leading dot (e.g., "csv").
by_daybool, default=False: If True, nest outputs under YYYY/MM/DD using UTC dates.
add_secretbool, default=False: If True, append a cryptographically strong random token, making names harder to guess. UUID4 already provides uniqueness; this option is for opacity when filenames may be exposed publicly.
privatebool, default=False: If True, force adding an extra random token (opacity). This is a more user-friendly alias for “make it hard to guess” and implies secret token behavior regardless of add_secret.
mkdirbool, default=True: If True, create the target directory (parents included).

Parameters:

root (Path)
default_prefix (str)
default_ext (str)
by_day (bool)
add_secret (bool)
private (bool)
mkdir (bool)

See also

make_path: Convenience wrapper callable with zero arguments.
uuid.uuid4: UUID generator used for collision resistance.
secrets.token_hex: Optional token source when add_secret=True.

Notes

Generated filename format (default):

{prefix}-{YYYYMMDDTHHMMSSmmmZ}-{counter:06d}-{uuid4hex}[ -{secret} ].{ext}

Examples

Create a path with defaults (UTC date folders):

>>> from scikitplot.utils._path import PathNamer
>>> namer = PathNamer()
>>> path = namer.make_path()
>>> path.parts[-1].startswith("file-")
True

Write outputs under a project directory:

>>> from pathlib import Path
>>> namer = PathNamer(
...     root=Path("artifacts"), default_prefix="report", default_ext="csv"
... )
>>> p = namer.make_path()
>>> p.as_posix().startswith("artifacts/")
True
>>> namer = PathNamer(root="~/artifacts", default_prefix="run", default_ext="json")
>>> p = namer.make_path()
>>> p.name.startswith("run-")
True

Disable date folders and group under a custom subdirectory:

>>> namer = PathNamer(
...     root=Path("output"),
...     by_day=False,
...     default_prefix="snapshot",
...     default_ext="parquet",
... )
>>> p = namer.make_path(subdir="models")
>>> "models" in p.as_posix()
True

Generate only the filename (no directory):

>>> fname = namer.make_filename(prefix="metrics", ext="json")
>>> fname.startswith("metrics-")
True
>>> fname.endswith(".json")
True

Private (unguessable) names:

>>> namer = PathNamer(
...     root="output", default_prefix="report", default_ext="csv", private=True
... )
>>> p = namer.make_path()
>>> p.name.endswith(".csv")
True

add_secret: bool = False#

by_day: bool = False#

default_ext: str = ''#

default_prefix: str = 'file'#

make_filename(prefix=None, ext=None, *, now=None)[source]#

Create a unique, portable filename.

Parameters:

prefixstr or None, default=None: Filename prefix. If None, uses default_prefix.
extstr or None, default=None: File extension. If None, uses default_ext.
nowdatetime or None, default=None: Timestamp to use. If None, uses current time in UTC. Naive datetimes are treated as UTC.

Returns:

filenamestr: A filename (no directory) suitable for common filesystems.

Parameters:

prefix (str | None)
ext (str | None)
now (datetime | None)

Return type:

str

make_path(prefix=None, ext=None, *, subdir=None, now=None)[source]#

Create a full path (folder + unique filename).

Parameters:

prefixstr or None, default=None: Filename prefix. If None, uses default_prefix.
extstr or None, default=None: File extension. If None, uses default_ext.
subdirstr or None, default=None: Optional subdirectory (sanitized) when by_day=False.
nowdatetime or None, default=None: Timestamp to use. If None, uses current time in UTC. Naive datetimes are treated as UTC.

Returns:

pathpathlib.Path: Full path to a unique file location.

Parameters:

prefix (str | None)
ext (str | None)
subdir (str | None)
now (datetime | None)

Return type:

Path

PathNamer#

This Page