swh.core.nar module

class swh.core.nar.Nar(hash_names: List[str], exclude_vcs: bool = False, vcs_type: str | None = 'git', debug: bool = False)

Bases: object

NAR serializer.

This builds the NAR structure and serializes it as per the phd thesis from Eelco Dolstra thesis. See https://edolstra.github.io/pubs/phd-thesis.pdf.

For example, this tree on a filesystem:

$ tree foo
foo
├── bar
│   └── exe
└── baz

1 directory, 2 files

serializes as:

nix-archive-1(typedirectoryentry(namebarnode(typedirectoryentry(nameexenode(typeregularexecutablecontents<Content of file foo/bar/exe>))))entry(namebaznode(typeregularcontents<Content of file foo/baz>)))

For reability, the debug mode prints the following:

nix-archive-1
  (
  type
  directory
    entry
    (
    name
    bar
    node
      (
      type
      directory
        entry
        (
        name
        exe
        node
          (
          type
          regular
          executable

          contents
          <Content of file foo/bar/exe>
          )
        )
      )
    )
    entry
    (
    name
    baz
    node
      (
      type
      regular
      contents
      <Content of file foo/baz>
     )
   )
 )

Note: “<Content of file $name>” is a placeholder for the actual file content

str_(thing: str | BufferedReader | list) → None

Compute the nar serialization format on ‘thing’ and compute its hash.

This is the function named named ‘str’ in Figure 5.2 p.93 (page 101 of pdf) [1]

[1] https://edolstra.github.io/pubs/phd-thesis.pdf

update(chunk: bytes) → None

serialize(fso: Path) → bytes

digest() → Dict[str, bytes]

Compute the hash results with bytes format.

hexdigest() → Dict[str, str]

Compute the hash results with hex format.

b64digest() → Dict[str, str]

Compute the hash results with b64 format.

b32digest() → Dict[str, str]

Compute the hash results with b32 format.

swh.core.nar.compute_nar_hashes(filepath: Path, hash_names: List[str] = ['sha256'], is_tarball=True, top_level=True) → Dict[str, str]

Compute nar checksums dict out of a filepath (tarball or plain file).

If it’s a tarball, this uncompresses the tarball in a temporary directory to compute the nar hashes (and then cleans it up).

Parameters:

• filepath – The tarball (if is_tarball is True) or a filepath

• hash_names – The list of checksums to compute

• is_tarball – Whether filepath represents a tarball or not

• top_level – Whether we want to compute the top-level directory (of the tarball) hashes. This is only useful when used with ‘is_tarball’ at True.

Returns:

The dict of checksums values whose keys are present in hash_names.

swh.core.nar.nar_serialize(path: Path, exclude_vcs: bool = False, vcs_type: str | None = 'git') → bytes

Return the NAR serialization of a path.

Parameters:

• path – The path to NAR serialize, can be a file or a directory.

• exclude_vcs – Whether to exclude VCS related directories (.git for instance).

• vcs_type – The type of VCS to exclude related directories, default to git.

Returns:

The NAR serialization of the path.

swh.core.nar.nar_unpack(nar_path: str, dest_path: str) → None

Unpack a NAR archive (possibly compressed with xz or bz2) to a path.

Please note that a nar archive can contain a single file instead of multiple files and directories, in that case dest_path will target a file after the unpacking.

Parameters:

• nar_archive_path – A path to a NAR archive.

• dest_path – The destination path where the NAR archive is extracted.