The `ObjectCollection` class¶

gamslib.objectcsv.objectcollection.ObjectCollection ¶

ObjectCollection()

Represents a collection of metadata for multiple GAMS objects and their datastreams.

Used to aggregate, save, load, and distribute object and datastream metadata between individual object directories and combined CSV/XLSX files.

Initialize an empty ObjectCollection.

objects `instance-attribute` ¶

objects = {}

datastreams `instance-attribute` ¶

datastreams = {}

collect_from_objects ¶

collect_from_objects(root_dir)

Collect metadata from all object directories below root_dir.

PARAMETER	DESCRIPTION
`root_dir`	Directory containing object folders. TYPE: `Path`

RAISES	DESCRIPTION
`ValueError`	If object metadata (CSV) is missing for any object directory.

distribute_to_objects ¶

distribute_to_objects(root_dir)

Distribute aggregated metadata to individual object directories.

Updates object.csv and datastreams.csv files in each object directory.

PARAMETER	DESCRIPTION
`root_dir`	Directory containing object folders. TYPE: `Path`

RETURNS	DESCRIPTION
`tuple[int, int]`	tuple[int, int]: Number of updated objects and datastreams.

RAISES	DESCRIPTION
`UserWarning`	If an object directory does not exist.

count_objects ¶

count_objects()

Return the number of objects in the collection.

RETURNS	DESCRIPTION
`int`	Number of objects. TYPE: `int`

count_datastreams ¶

count_datastreams()

Return the total number of datastreams in the collection.

RETURNS	DESCRIPTION
`int`	Number of datastreams. TYPE: `int`

save_to_csv ¶

save_to_csv(obj_file=None, ds_file=None)

Save object and datastream metadata to two CSV files.

There is on relevant difference: The collected datastreams have a different dspath than the datastreams in the individual object directories. The dspath in the collection has the recid as prefix, while the dspath in the individual object directories is relative to the object directory.

We need this to keep track of which datastream belongs to which object in the collection, but we want to avoid an additional column for the object id in the datastreams CSV, because:

the format of the csv should not be different
an extra column would be more tempting to be accidentally modified, which would break the connection between datastreams and objects
we can easily reconstruct the object id from the dspath by splitting it at the first slash

PARAMETER	DESCRIPTION
`obj_file`	Path for object metadata CSV. Defaults to 'all_objects.csv'. TYPE: `Path \| None` DEFAULT: `None`
`ds_file`	Path for datastream metadata CSV. Defaults to all_datastreams.csv'. TYPE: `Path \| None` DEFAULT: `None`

save_to_xlsx ¶

save_to_xlsx(xlsx_file=None)

Save object and datastream metadata to a single XLSX file with two sheets.

PARAMETER	DESCRIPTION
`xlsx_file`	Path for XLSX file. Defaults to 'all_objects.xlsx'. TYPE: `Path \| None` DEFAULT: `None`

Returns: None

load_from_csv ¶

load_from_csv(obj_file=None, ds_file=None)

Load object and datastream metadata from two CSV files.

PARAMETER	DESCRIPTION
`obj_file`	Path for object metadata CSV. Defaults to 'all_objects.csv'. TYPE: `Path \| None` DEFAULT: `None`
`ds_file`	Path for datastream metadata CSV. Defaults to all_datastreams.csv'. TYPE: `Path \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`FileNotFoundError`	If either CSV file does not exist.

load_from_xlsx ¶

load_from_xlsx(xlsx_file=None)

Load object and datastream metadata from a single XLSX file with two sheets.

PARAMETER	DESCRIPTION
`xlsx_file`	Path for XLSX file. Defaults to 'all_objects.xlsx'. TYPE: `Path \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`FileNotFoundError`	If the XLSX file does not exist.

The ObjectCollection class¶