directory.archive ================= .. py:module:: directory.archive Attributes ---------- .. autoapisummary:: directory.archive.UnknownFieldType directory.archive.UNKNOWN_FIELD Exceptions ---------- .. autoapisummary:: directory.archive.DirectoryFileNotFound Classes ------- .. autoapisummary:: directory.archive._Sentinel directory.archive.FieldParser directory.archive.DirectoryArchiveReader directory.archive.DirectoryArchiveWriter directory.archive.DirectoryArchive directory.archive.DirectoryZipArchive Module Contents --------------- .. py:type:: UnknownFieldType :canonical: 'Literal[_Sentinel.UNKNOWN_FIELD]' .. py:class:: _Sentinel(*args, **kwds) Bases: :py:obj:`enum.Enum` Create a collection of name/value pairs. Example enumeration: >>> class Color(Enum): ... RED = 1 ... BLUE = 2 ... GREEN = 3 Access them by: - attribute access:: >>> Color.RED - value lookup: >>> Color(1) - name lookup: >>> Color['RED'] Enumerations can be iterated over, and know how many members they have: >>> len(Color) 3 >>> list(Color) [, , ] Methods can be added to enumerations, and members can have their own attributes -- see the documentation for details. .. py:attribute:: UNKNOWN_FIELD .. py:data:: UNKNOWN_FIELD .. py:exception:: DirectoryFileNotFound(file_id: str, entry_name: str, filename: str) Bases: :py:obj:`FileNotFoundError` File not found. .. py:attribute:: file_id .. py:attribute:: entry_name .. py:attribute:: filename exception filename .. py:class:: FieldParser(directory: onegov.directory.models.Directory, archive_path: pathlib.Path) Parses records read by the directory archive reader. .. py:attribute:: fields_by_human_id .. py:attribute:: fields_by_id .. py:attribute:: archive_path .. py:method:: get_field(key: str) -> onegov.form.parser.core.ParsedField | None CSV Files header parsing is inconsistent with the the internal id ( field.id) of the field. The headers are lovercased, so that the first will not yield the field, the second will also not success because characters like ( are not replaced by underscores. .. py:method:: parse_fileinput(key: str, value: str, field: onegov.form.parser.core.FileinputField) -> onegov.core.utils.Bunch | None .. py:method:: parse_multiplefileinput(key: str, value: str, field: onegov.form.parser.core.MultipleFileinputField) -> tuple[onegov.core.utils.Bunch, Ellipsis] .. py:method:: parse_generic(key: str, value: str, field: onegov.form.parser.core.ParsedField) -> object .. py:method:: parse_item(key: str, value: str) -> tuple[str, Any | None] | UnknownFieldType .. py:method:: parse(record: _typeshed.SupportsItems[str, str]) -> dict[str, Any | None] .. py:class:: DirectoryArchiveReader Reading part of :class:`DirectoryArchive`. .. py:attribute:: path :type: pathlib.Path .. py:method:: read(target: onegov.directory.models.Directory | None = None, skip_existing: bool = True, limit: int = 0, apply_metadata: bool = True, after_import: collections.abc.Callable[[onegov.directory.models.DirectoryEntry], Any] | None = None) -> onegov.directory.models.Directory Reads the archive resulting in a dictionary and entries. :param target: Uses the given directory as a target for the read. Otherwise, a new directory is created in memory (default). :param skip_existing: Excludes already existing entries from being added to the directory. Only applies if target is not None. :param limit: Limits the number of records which are imported. If the limit is reached, the read process silently ignores all extra items. :param apply_metadata: True if the metadata found in the archive should be applied to the directory. :param after_import: Called with the newly added entry, right after it has been added. .. py:method:: apply_metadata(directory: onegov.directory.models.Directory, metadata: dict[str, Any]) -> onegov.directory.models.Directory Applies the metadata to the given directory and returns it. .. py:method:: read_metadata() -> dict[str, Any] Returns the metadata as a dictionary. .. py:method:: read_data() -> collections.abc.Sequence[dict[str, Any]] Returns the entries as a sequence of dictionaries. .. py:method:: read_data_from_json() -> list[dict[str, Any]] .. py:method:: read_data_from_csv() -> tuple[dict[str, Any], Ellipsis] .. py:method:: read_data_from_xlsx() -> tuple[dict[str, Any], Ellipsis] .. py:class:: DirectoryArchiveWriter Writing part of :class:`DirectoryArchive`. .. py:attribute:: path :type: pathlib.Path .. py:attribute:: format :type: Literal['json', 'csv', 'xlsx'] .. py:attribute:: transform :type: FieldValueTransform .. py:method:: write(directory: onegov.directory.models.Directory, *args: Any, entry_filter: DirectoryEntryFilter | None = None, query: sqlalchemy.orm.Query[onegov.directory.models.DirectoryEntry] | None = None, **kwargs: Any) -> None Writes the given directory. .. py:method:: write_directory_metadata(directory: onegov.directory.models.Directory) -> None Writes the metadata. .. py:method:: write_directory_entries(directory: onegov.directory.models.Directory, entry_filter: DirectoryEntryFilter | None = None, query: sqlalchemy.orm.Query[onegov.directory.models.DirectoryEntry] | None = None) -> None Writes the directory entries. Allows filtering with custom entry_filter function as well as passing a query object .. py:method:: write_paths(session: sqlalchemy.orm.Session, paths: dict[str, str], fid_to_entry: dict[str, str] | None = None) -> None Writes the given files to the archive path. :param session: The database session in use. :param paths: A dictionary with each key being a file id and each value being a path where this file id should be written to. :param fid_to_entry: A dictionary with the mapping of the file id to the entry name .. py:method:: write_json(path: pathlib.Path, data: onegov.core.types.JSON_ro) -> None .. py:method:: write_xlsx(path: pathlib.Path, data: collections.abc.Iterable[dict[str, Any]]) -> None .. py:method:: write_csv(path: pathlib.Path, data: collections.abc.Iterable[dict[str, Any]]) -> None .. py:class:: DirectoryArchive(path: _typeshed.StrPath, format: Literal['json', 'csv', 'xlsx'] = 'json', transform: FieldValueTransform | None = None) Bases: :py:obj:`DirectoryArchiveReader`, :py:obj:`DirectoryArchiveWriter` Offers the ability to read/write a directory and its entries to a folder. Usage:: archive = DirectoryArchive('/tmp/directory') archive.write() archive = DirectoryArchive('/tmp/directory') archive.read() The archive content is as follows: - metadata.json (contains the directory data) - data.json/data.csv/data.xlsx (contains the directory entries) - .//. (files referenced by the directory entries) The directory entries are stored as json, csv or xlsx. Json is preferred. .. py:attribute:: path .. py:attribute:: format :value: 'json' .. py:attribute:: transform .. py:class:: DirectoryZipArchive(path: _typeshed.StrPath, *args: Any, **kwargs: Any) Offers the same interface as the DirectoryArchive, additionally zipping the folder on write and extracting the zip on read. .. py:attribute:: format :type: Literal['zip'] :value: 'zip' .. py:attribute:: path .. py:attribute:: temp .. py:attribute:: archive .. py:method:: from_buffer(buffer: SupportsReadAndSeek) -> Self :classmethod: Creates a zip archive instance from a file object in memory. .. py:method:: write(directory: onegov.directory.models.Directory, *args: Any, **kwargs: Any) -> None .. py:method:: read(*args: Any, **kwargs: Any) -> onegov.directory.models.Directory .. py:method:: compress() -> None .. py:method:: extract() -> None