Metadata-Version: 2.5
Name: hatch-zipped-directory
Version: 0.3.0
Summary: A custom builder to build zipped directories
Project-URL: Source, https://github.com/dairiki/hatch-zipped-directory
Project-URL: Changes, https://github.com/dairiki/hatch-zipped-directory/blob/master/CHANGES.md
Author-email: Jeff Dairiki <dairiki@dairiki.org>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: hatch,packaging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Framework :: Hatch
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: System :: Archiving :: Packaging
Requires-Python: >=3.10
Requires-Dist: hatchling
Description-Content-Type: text/markdown

# hatch-zipped-directory

[![PyPI - Version](https://img.shields.io/pypi/v/hatch-zipped-directory.svg?logo=pypi&style=plastic "Latest PyPI version")](https://pypi.org/project/hatch-zipped-directory)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hatch-zipped-directory.svg?style=plastic "PyPI - Supported Python Versions")
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/dairiki/hatch-zipped-directory/tests.yml?style=plastic&label=tests)](https://github.com/dairiki/hatch-zipped-directory/actions/workflows/tests.yml)
[![GitHub stars](https://img.shields.io/github/stars/dairiki/hatch-zipped-directory?logo=github&style=plastic)](https://github.com/dairiki/hatch-zipped-directory)


-----

This is a [Hatch](https://hatch.pypa.io/latest/) plugin that provides
a custom builder to support building zip archives for quasi-manual
installation into various foreign package installation systems.
(Specifically, I use this for packaging
[Inkscape](https://inkscape.org/) extensions and symbols libraries,
but it may be useful in other contexts, such as deploying to cloud
compute platforms.)

The builder creates a zip archive.  All the contents of the zip
archive will be included under a single specific top-level directory.
The default name of the top-level directory is a file-name-safe
version of the project name, however the name of the directory may be
configured by setting the `install-name` key in the target-specific
configuration section.
This behavior may be disabled by setting `install-name = ''`.

In addition to whatever files are selected for inclusion in the
archive via Hatch’s regular [build configuration
settings](https://hatch.pypa.io/latest/config/build/), any configured
project README and license files will be included in the top level of
the install directory within the zip archive.

As well, a `METADATA.json` file containing the project metadata in
JSON format (as described in
[PEP 566](https://peps.python.org/pep-0566/#json-compatible-metadata))
will be included in the top level of the install directory within the
zip archive.


## Example

Assume a project source directory looking something like:
```
.
├── pyproject.toml
├── LICENSE.txt
├── README.md
├── src
│   ├── subdir
│   │   ├── data.txt
│   │   └── more-code.py
│   └── my-code.py
└── tests
    └── test_foo.py
```

Where `pyproject.toml` looks like:
```toml
[build-system]
requires = [
    "hatchling",
    "hatch-zipped-directory",
]
build-backend = "hatchling.build"

[project]
name = "test-project"
version = "0.42"

[tool.hatch.build.targets.zipped-directory]
install-name = "org.example.test"
sources = [
    "/src",
]
```

Then, running
```sh
hatch build --target zipped-directory
```

will build a zip archive named `dist/test_project-0.42.zip` with the following
structure:
```
.
└── org.example.test
    ├── LICENSE.txt
    ├── METADATA.json
    ├── README.md
    ├── my-code.py
    └── subdir
        ├── data.txt
        └── more-code.py
```

## Reproducible Builds

By default, this plugin attempts to build [reproducible][reproducible
builds] archives by setting the timestamps of the zip entries to a
fixed value. When building in reproducible mode, the UNIX file modes
of the archive entries is also normalized (to either 0644 or 0755
depending on whether the file is executable).  As well, in
reproducible mode, the _"create system"_ flag in the zip file headers
are forced to _Unix_, even when running under Windows.

The timestamp used for reproducible builds may be configured by
setting the `SOURCE_DATE_EPOCH` environment variable.

Reproducible builds may be disabled by setting `reproducible = false`
in an appropriate section of `pyproject.toml` or `hatch.toml`.  See
Hatch’s documentation on [Build Configuration] for details.

## Change History

A [change log][CHANGES.md] is maintained in our [GitHub repository][repo].

[CHANGES.md]: https://github.com/dairiki/hatch-zipped-directory/blob/master/CHANGES.md (CHANGES.md in the GitHub master branch)
[repo]: https://github.com/dairiki/hatch-zipped-directory

## Author

Jeff Dairiki <dairiki@dairiki.org>

## License

`hatch-zipped-directory` is distributed under the terms of the
[MIT](https://spdx.org/licenses/MIT.html) license.

[reproducible builds]: https://hatch.pypa.io/latest/config/build/#reproducible-builds
[Build Configuration]: https://hatch.pypa.io/latest/config/build/
