2.8.1.5. pycsamt.site.export#

Functions

pack_zip(sites, out_zip, *[, template, ...])

Pack a set of sites into a zip archive using a filename template.

write_site(site, path)

Write a single site (EDI) to a target path.

write_sites(sites, outdir, *[, template, ...])

Write a collection of sites to a directory using a filename template.
pycsamt.site.export.write_site(site, path)[source]

Write a single site (EDI) to a target path.

This is a thin, best-effort adapter around several common EDI writer spellings. The function will create parent directories as needed and then try, in order, the following methods on site until one succeeds:

  1. write(new_edifn=path)

  2. write(path)

  3. to_file(path)

  4. save(path)

If none of these exist or succeed, a RuntimeError is raised.

Parameters:

  • site (Any) – An EDI-like object. It can be a pycsamt.seg.edi.EDIFile or any object exposing one of the writer methods listed above.

  • path (str or pathlib.Path) – Destination file path. Parent directories are created if they do not exist.

Returns:

The resolved output path.

Return type:

pathlib.Path

Notes

This function does not enforce overwrite policy. Whether an existing file is replaced depends on the underlying writer implementation of the provided site object.

Examples

>>> from pathlib import Path
>>> from pycsamt.site.export import write_site
>>> class Dummy:
...     def to_file(self, p):  # minimal writer
...         Path(p).write_text("# dummy edi\\n", encoding="utf-8")
>>> out = write_site(Dummy(), Path("out") / "S01.edi")
>>> out.name
'S01.edi'
>>> out.exists()
True

See also

pycsamt.site.export.write_sites

Batch writing with templated filenames and optional manifest.

pycsamt.site.export.pack_zip

Archive a set of sites into a zip.

References

[write-site-1]

Python Software Foundation. “pathlib” and “io” modules.

pycsamt.site.export.write_sites(sites, outdir, *, template='{station}.edi', exist_ok=False, manifest_csv=None)[source]

Write a collection of sites to a directory using a filename template.

The function accepts many input forms (Sites, an EDICollection, any iterable of EDI-like objects, or a single object) and writes each item to outdir. Filenames are rendered from a context and the template string.

Supported template keys (filled via a safe formatter):

  • {station} : current station name

  • {index} : zero-based index in the iteration order

  • {lat}, {lon}, {elev} : header coordinates, or NaN

  • {chainage} : optional header chainage, or NaN

If the rendered name does not end with .edi, the extension is appended automatically.

Parameters:

  • sites (Any) – A Sites instance, an EDICollection, any iterable of EDI-like objects, or a single EDI-like object. EDI-like means it implements one of: write(new_edifn=...), write(...), to_file(...), or save(...).

  • outdir (str or pathlib.Path) – Output directory. It is created if it does not exist.

  • template (str, optional) – Filename template. Defaults to "{station}.edi".

  • exist_ok (bool, optional) – If False (default), raise FileExistsError on the first name collision inside outdir. If True, allow overwriting subject to the writer behavior.

  • manifest_csv (str or pathlib.Path or None, optional) – If provided, write a CSV manifest with one row per written site. Columns are: index, station, lat, lon, elev, chainage, filename, path.

Returns:

Paths to the files written, in the same order as the input iteration.

Return type:

list of pathlib.Path

Notes

The index used in templating and in the manifest is the zero-based position in the input order. Coordinate fields come from the EDI header when available; missing values are written as NaN.

Examples

>>> from pathlib import Path
>>> from pycsamt.site.export import write_sites
>>> class EdiToFile:
...     def __init__(self, name):
...         self._n = name
...
...     def to_file(self, p):
...         Path(p).write_text(f"# {self._n}\\n", encoding="utf-8")
...
...     # station name is taken from header helpers when present,
...     # but the template can still use {index}.
>>> outdir = Path("eds_out")
>>> paths = write_sites(
...     [EdiToFile("S01"), EdiToFile("S02")],
...     outdir,
...     template="{index:03d}_{station}",
... )
>>> [p.exists() for p in paths]
[True, True]

>>> # Write with a manifest
>>> mpath = Path("eds_out") / "manifest.csv"
>>> _ = write_sites(
...     [EdiToFile("S01"), EdiToFile("S02")],
...     outdir,
...     template="{station}",
...     exist_ok=True,
...     manifest_csv=mpath,
... )
>>> mpath.exists()
True

See also

pycsamt.site.base.Sites.write

Higher-level convenience bound to a Sites collection.

pycsamt.site.export.pack_zip

Create a zip archive instead of a directory tree.

References

[write-sites-1]

Python Software Foundation. “csv” module.

pycsamt.site.export.pack_zip(sites, out_zip, *, template='{station}.edi', manifest_csv=None)[source]

Pack a set of sites into a zip archive using a filename template.

Each input item is written to a temporary directory first, then added to the out_zip archive using ZIP_DEFLATED. Filenames inside the archive are rendered from the same context as in write_sites(). If a name lacks the .edi suffix, it is appended automatically.

Optionally, a CSV manifest can be written alongside the archive.

Parameters:

  • sites (Any) – A Sites instance, an EDICollection, any iterable of EDI-like objects, or a single EDI-like object.

  • out_zip (str or pathlib.Path) – Destination zip file path. Parent directories are created as needed.

  • template (str, optional) – Filename template for entries stored in the archive. Defaults to "{station}.edi".

  • manifest_csv (str or pathlib.Path or None, optional) – If provided, write a CSV manifest next to the zip. Columns: index, station, lat, lon, elev, chainage, filename, path.

Returns:

The path to the created zip archive.

Return type:

pathlib.Path

Notes

Files are staged in a temporary directory and then compressed with zipfile.ZIP_DEFLATED. The index used in templating and the manifest corresponds to the input iteration order. This function does not delete or modify any original EDI sources.

Examples

>>> from pathlib import Path
>>> from zipfile import ZipFile
>>> from pycsamt.site.export import pack_zip
>>> class EdiSave:
...     def __init__(self, name):
...         self._n = name
...
...     def to_file(self, p):
...         Path(p).write_text(f"# {self._n}\\n", encoding="utf-8")
>>> zpath = Path("out_bundle") / "sites.zip"
>>> out = pack_zip(
...     [EdiSave("A01"), EdiSave("A02")],
...     zpath,
...     template="{station}.edi",
...     manifest_csv=Path("out_bundle") / "manifest.csv",
... )
>>> out == zpath, zpath.exists()
(True, True)
>>> with ZipFile(zpath, "r") as zf:
...     sorted(zf.namelist())
['A01.edi', 'A02.edi']

See also

pycsamt.site.export.write_sites

Write files to a directory instead of an archive.

References

[pack-zip-1]

Python Software Foundation. “zipfile” module.