Distribution Utilities partis.pyproj.dist_file

dist_base

class dist_base(outname, outdir=None, tmpdir=None, logger=None, named_dirs=None)

Bases: ABC

Builder for file distribution

Parameters:

• outname (str) – Name of output file.

• outdir (str | pathlib.Path) – Path to directory where the file should be copied after completing build.

• tmpdir (None | str | pathlib.Path) – If not None, uses the given directory to place the temporary file(s) before copying to final location. May be the same as outdir.

• named_dirs (None | Dict[ str, str | pathlib.PurePosixPath ]) – Mapping of specially named directories within the distribution. By default a named directory { ‘root’ : ‘.’ } will be added, unless overridden with another directory name.

• logger (None | logging.Logger) – Logger to which any status information is to be logged.

outpath

Path to final output file location

Type:

pathlib.Path

named_dirs

Mapping of specially named directories within the distribution

Type:

Dict[ str, pathlib.PurePosixPath ]

opened

Build temporary file has been opened for writing

Type:

bool

finalized

Build temporary file has been finalized.

Type:

bool

closed

Build temporary file has been closed

Type:

bool

copied

Build temporary has been copied to outpath location

Type:

bool

records

Recorded list of path, hash, and size (bytes) of files added to distribution

Type:

List[ Tuple[ pathlib.PurePosixPath, str, int ] ]

record_hash

Final hash value of the record after being finalized

Note

Not all distribution implementations will create a hash of the record

Type:

None | str

exists(dst)

Behaviour similar to os.path.exists for entries in the distribution file

Parameters:

dst (str | PurePosixPath) –

Returns:

exists (bool)

write(dst, data, mode=None, record=True)

Write data into the distribution file

Parameters:

• dst (str | PurePosixPath) –

• data (bytes) –

• mode (int) –

• record (bool) – Add file to the record

makedirs(dst, mode=None, exist_ok=False, record=True)

Behaviour similar to os.makedirs into the distribution file

Parameters:

• dst (str | PurePosixPath) –

• mode (int) –

• exist_ok (bool) –

• record (bool) – Add file to the record

Note

Some archive file types do not need to explicitly create directories, but this is given in case an implementation needs to create a directory before creating files within the directory.

copyfile(src, dst, mode=None, exist_ok=False, record=True)

Behaviour similar to shutil.copyfile into the distribution file

Parameters:

• src (str | pathlib.Path) –

• dst (str | pathlib.PurePosixPath) –

• mode (int) –

• exist_ok (bool) –

• record (bool) – Add file to the RECORD

copytree(src, dst, ignore=None, exist_ok=False, record=True)

Behaviour similar to shutil.copytree into the distribution file

Parameters:

• src (str | pathlib.Path) –

• dst (str | pathlib.PurePosixPath) –

• ignore (None | callable) –

  If not None, callable(src, names) -> ignored_names

  See shutil.copytree()

• exist_ok (bool) –

• record (bool) – Add all files to the RECORD

open()

Opens the temporary distribution file

Returns:

self (dist_base)

record(dst, data)

Creates a record for an added file

This produces an sha256 hash of the data and associates a record with the item

Parameters:

• dst (str | PurePosixPath) – Path of item within the distribution

• data (bytes) – Binary data that was added

Returns:

None

close(finalize=True, copy=True)

Closes the temporary distribution file

Parameters:

• finalize (bool) – If true, finalizes the temporary distribution file before closing

• copy (bool) – If true, copies the temporary file to final location after closing

Returns:

None

assert_open()

Raises exception if temporary file is not open

assert_recordable()

Raises exception if temporary file has already been finalized

abstract create_distfile()

Creates and opens a temporary distribution file into which files are copied

abstract finalize()

Finalizes the distribution file before being closed

Returns:

record_hash (None | str) – sha256 hash of the record

Note

Not all distribution implementations will create/return a hash of the record

abstract close_distfile()

Closes the temporary distribution file

abstract copy_distfile()

Copies the temporary distribution file to it’s final location

abstract remove_distfile()

Deletes the temporary distribution file

dist_targz

class dist_targz(outname, outdir=None, tmpdir=None, named_dirs=None, logger=None)

Bases: dist_base

Builds a tar-file with gz compression

Example

import tempfile

with tempfile.TemporaryDirectory() as tmpdir:

  import os
  import os.path

  pkg_dir = os.path.join( tmpdir, 'src', 'my_package' )
  out_dir = os.path.join( tmpdir, 'build' )

  os.makedirs( pkg_dir )

  with open( os.path.join( pkg_dir, 'module.py' ), 'w' ) as fp:
    fp.write("print('hello')")

  from partis.pyproj import (
    dist_targz )

  with dist_targz(
    outname = 'my_dist.tar.gz',
    outdir = out_dir ) as dist:

    dist.copytree(
      src = pkg_dir,
      dst = 'my_package' )

create_distfile()

Creates and opens a temporary distribution file into which files are copied

close_distfile()

Closes the temporary distribution file

copy_distfile()

Copies the temporary distribution file to it’s final location

remove_distfile()

Deletes the temporary distribution file

write(dst, data, mode=None, record=True)

Write data into the distribution file

Parameters:

• dst (str | PurePosixPath) –

• data (bytes) –

• mode (int) –

• record (bool) – Add file to the record

finalize()

Finalizes the distribution file before being closed

Returns:

record_hash (None | str) – sha256 hash of the record

Note

Not all distribution implementations will create/return a hash of the record

exists(dst)

Behaviour similar to os.path.exists for entries in the distribution file

Parameters:

dst (str | PurePosixPath) –

Returns:

exists (bool)

dist_zip

class dist_zip(outname, outdir=None, tmpdir=None, named_dirs=None, logger=None)

Bases: dist_base

Builds a zip file

Example

import tempfile

with tempfile.TemporaryDirectory() as tmpdir:

  import os
  import os.path

  pkg_dir = os.path.join( tmpdir, 'src', 'my_package' )
  out_dir = os.path.join( tmpdir, 'build' )

  os.makedirs( pkg_dir )

  with open( os.path.join( pkg_dir, 'module.py' ), 'w' ) as fp:
    fp.write("print('hello')")

  from partis.pyproj import (
    dist_zip )

  with dist_zip(
    outname = 'my_dist.zip',
    outdir = out_dir ) as dist:

    dist.copytree(
      src = pkg_dir,
      dst = 'my_package' )

create_distfile()

Creates and opens a temporary distribution file into which files are copied

close_distfile()

Closes the temporary distribution file

copy_distfile()

Copies the temporary distribution file to it’s final location

remove_distfile()

Deletes the temporary distribution file

write(dst, data, mode=None, record=True)

Write data into the distribution file

Parameters:

• dst (str | PurePosixPath) –

• data (bytes) –

• mode (int) –

• record (bool) – Add file to the record

finalize()

Finalizes the distribution file before being closed

Returns:

record_hash (None | str) – sha256 hash of the record

Note

Not all distribution implementations will create/return a hash of the record

exists(dst)

Behaviour similar to os.path.exists for entries in the distribution file

Parameters:

dst (str | PurePosixPath) –

Returns:

exists (bool)

dist_source_targz

class dist_source_targz(pkg_info, outdir=None, tmpdir=None, logger=None)

Bases: dist_targz

Build a source distribution *.tar.gz file

Parameters:

• pkg_info (PkgInfo) –

• outdir (None | str | pathlib.Path) – Path to directory where the wheel file should be copied after completing build.

• tmpdir (None | str | pathlib.Path) – If not None, uses the given directory to place the temporary wheel file before copying to final location. My be the same as outdir.

• logger (None | logging.Logger) – Logger to use.

Example

import tempfile

with tempfile.TemporaryDirectory() as tmpdir:

  import os
  import os.path

  pkg_dir = os.path.join( tmpdir, 'src', 'my_package' )
  out_dir = os.path.join( tmpdir, 'build' )

  os.makedirs( pkg_dir )

  with open( os.path.join( pkg_dir, 'module.py' ), 'w' ) as fp:
    fp.write("print('hello')")

  from partis.pyproj import (
    PkgInfo,
    dist_source_targz )

  pkg_info = PkgInfo(
    project = dict(
      name = 'my-package',
      version = '1.0' ) )

  with dist_source_targz(
    pkg_info = pkg_info,
    outdir = out_dir ) as sdist:

    sdist.copytree(
      src = './src',
      dst = os.path.join( sdist.base_path, 'src' ) )

finalize()

Finalizes the distribution file before being closed

Returns:

record_hash (None | str) – sha256 hash of the record

Note

Not all distribution implementations will create/return a hash of the record

dist_binary_wheel

class dist_binary_wheel(*, pkg_info, build='', compat=None, outdir=None, tmpdir=None, logger=None, gen_name=None)

Bases: dist_zip

Build a binary distribution PEP 427, PEP 491 wheel file *.whl

Parameters:

• pkg_info (PkgInfo) –

• build (str) – Build tag. Must start with a digit, or be an empty string.

• compat (List[ Tuple[str,str,str] ] | List[ CompatibilityTags ]) – List of build compatability tuples of the form ( py_tag, abi_tag, plat_tag ). e.g. ( ‘py3’, ‘abi3’, ‘linux_x86_64’ )

• outdir (str) – Path to directory where the wheel file should be copied after completing build.

• tmpdir (None | str) – If not None, uses the given directory to place the temporary wheel file before copying to final location. My be the same as outdir.

• logger (None | logging.Logger) – Logger to use.

• gen_name (str) – Name to use as the ‘Generator’ of the wheel file

Example

import tempfile

with tempfile.TemporaryDirectory() as tmpdir:

  import os
  import os.path

  pkg_dir = os.path.join( tmpdir, 'src', 'my_package' )
  out_dir = os.path.join( tmpdir, 'build' )

  os.makedirs( pkg_dir )

  with open( os.path.join( pkg_dir, 'module.py' ), 'w' ) as fp:
    fp.write("print('hello')")

  from partis.pyproj import (
    PkgInfo,
    dist_binary_wheel )

  pkg_info = PkgInfo(
    project = dict(
      name = 'my-package',
      version = '1.0' ) )

  with dist_binary_wheel(
    pkg_info = pkg_info,
    outdir = out_dir ) as bdist:

    bdist.copytree(
      src = pkg_dir,
      dst = 'my_package' )

See also

• https://www.python.org/dev/peps/pep-0427

• https://www.python.org/dev/peps/pep-0491

• https://www.python.org/dev/peps/pep-0660

finalize()

Finalizes the distribution file before being closed

Returns:

record_hash (None | str) – sha256 hash of the record

Note

Not all distribution implementations will create/return a hash of the record

check_top_level()

Discover the package top_level from record entries

encode_dist_info_wheel()

Generate content for .dist_info/WHEEL

Returns:

content (bytes)

encode_dist_info_record()

Generate content for .dist_info/RECORD

Returns:

• content (bytes)

• hash (str) – sha256 hash of the record file data