File Management Helpers

The submodule pydesignflow.filemgmt is independent of the core PyDesignFlow functionality. It is useful for managing VLSI library and design files that vary by attributes such as process corner, temperature, or voltage.

Key Features

  • checkfile and checkdir: Verify file/directory existence with error handling

  • FileCollection: Manage file sets with associated attributes

  • Pattern-based file discovery with FileCollection.frompattern

Basic Usage

The following example shows manual collection building:

from pydesignflow import filemgmt
from pathlib import Path

c = filemgmt.FileCollection()
c.add(Path("fast_hot.lib"),  speed='fast', temp=100)
c.add(Path("fast_cold.lib"), speed='fast', temp=-10)
c.add(Path("slow_hot.lib"),  speed='slow', temp=100)
c.add(Path("slow_cold.lib"), speed='slow', temp=-10)

# Get single file matching criteria
x = c.one(speed='slow', temp=100)  # returns Path("slow_hot.lib")

# Shorthand syntax
x = c(speed='slow', temp=100)  # same as above

Pattern-Based Discovery

Create collections from file naming patterns:

from pathlib import Path

def decode_lib(name):
    # Parse "fast_100" -> {'speed': 'fast', 'temp': 100}
    parts = name.split('_')
    return {'speed': parts[0], 'temp': int(parts[1])}

c = filemgmt.FileCollection.frompattern(
    Path("libs/"),
    pattern=r"(.*)\.lib",
    decoder=decode_lib
)

# Now use filtering as above
lib = c(speed='slow', temp=-10)

Reference

File management helpers for organizing VLSI library and design files.

This module provides utilities for managing collections of files with associated attributes (e.g., process corners, temperatures, voltages). It is independent of the core PyDesignFlow functionality.

exception pydesignflow.filemgmt.FileManagementError

Exception raised for file management related errors.

pydesignflow.filemgmt.checkfile(path: Path) → Path

Check that path exists and is a file, then return path.

Parameters:

path – Path to verify.

Returns:

The input path if validation succeeds.

Raises:

FileManagementError – If path does not exist or is not a file.

pydesignflow.filemgmt.checkdir(path: Path) → Path

Check that path exists and is a directory, then return path.

Parameters:

path – Path to verify.

Returns:

The input path if validation succeeds.

Raises:

FileManagementError – If path does not exist or is not a directory.

class pydesignflow.filemgmt.FileCollectionItem(path: Path, attrs: dict[str, object])

A file with associated attributes.

path

File path.

Type:

pathlib.Path

attrs

Dictionary of attributes (e.g., process corner, temperature).

Type:

dict[str, object]

class pydesignflow.filemgmt.FileCollection(items: list[FileCollectionItem] | None = None)

A collection of files with associated attributes.

Manages files of the same type (e.g., timing libraries, design files) that differ in attributes such as voltage, process corner, or temperature. Supports filtering, tagging, and pattern-based creation from directories.

tag(**attrs: dict[str, object])

Add attributes to all items in the collection.

Parameters:

**attrs – Attributes to add to each file.

Returns:

New FileCollection with updated attributes.

add(path: Path, **attrs: dict[str, object])

Add a file to the collection.

Parameters:

  • path – File path to add.

  • **attrs – Attributes for this file.

Raises:

FileManagementError – If file does not exist.

filter(missing_key_deselects: bool = False, **filters: dict[str, object])

Filter files by attributes.

Parameters:

  • missing_key_deselects – If True, exclude items that lack any filter key. If False (default), only check keys that exist.

  • **filters – Attribute filters (e.g., speed=’fast’, temp=100).

Returns:

New FileCollection with matching files.

one(missing_key_deselects: bool = False, **filters: dict[str, object])

Get the single file matching the filters.

Parameters:

  • missing_key_deselects – Passed to filter().

  • **filters – Attribute filters.

Returns:

Path of the unique matching file.

Raises:

FileManagementError – If no match or multiple matches found.

classmethod frompattern(dir: Path, pattern: str, decoder)

Create FileCollection using pattern and decoder function.

Parameters:

  • dir – Directory (Path) in which to locate files.

  • pattern – Regular expression (Python’s re module) for finding desired files.

  • decoder – Decoder function, receives first regular expression group string as argument, returns dictionary of file attributes.

Returns:

new FileCollection object