Metadata-Version: 2.4
Name: my-hello-world-sample
Version: 0.1.0
Summary: A minimal sample Python package demonstrating how to build a wheel and publish it to PyPI.
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: hello-world,packaging,pypi,sample
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# my-hello-world-sample

A minimal, publishable Python package. It does two things:

1. Says hello.
2. Ships a **bundled `.zip` archive inside the wheel**, so you can see how to
   include binary/package data in a distribution.

## Install

```bash
pip install my-hello-world-sample
```

## Usage

```python
from my_hello_world_sample import hello

print(hello())          # Hello, World!
print(hello("PyPI"))    # Hello, PyPI!
```

As a module:

```bash
python -m my_hello_world_sample
```

### Reading the bundled zip

The archive lives at `my_hello_world_sample/data/psmain.zip` inside the
installed package:

```python
from my_hello_world_sample import list_entries, read_entry

list_entries()                      # 869 entries
```

Most entries in the bundled archive are password-protected, so `read_entry()`
needs the archive password to decrypt them:

```python
read_entry("main/circular_backend-main/README.md", pwd="your-password")
```

Without `pwd`, `read_entry()` raises a `RuntimeError` explaining that the
entry is encrypted — it never silently returns garbage.

Point them at a different archive by name — any `.zip` in the `data/`
directory works:

```python
list_entries("my-other.zip")
```

## Project layout

```
.
├── pyproject.toml          # metadata + build configuration
├── README.md
├── LICENSE
├── .gitignore
└── src/
    └── my_hello_world_sample/
        ├── __init__.py     # public API + __version__
        ├── __main__.py     # python -m my_hello_world_sample
        ├── core.py         # hello()
        ├── assets.py       # zip accessors
        └── data/
            └── psmain.zip # bundled archive
```

## Development

```bash
python3 -m venv .venv
.venv/bin/python -m pip install build twine
.venv/bin/python -m build          # writes to dist/
```

Build artifacts land in `dist/`:

- `my_hello_world_sample-0.1.0-py3-none-any.whl` — the wheel
- `my_hello_world_sample-0.1.0.tar.gz` — the source distribution

Verify the wheel really contains the archive before publishing:

```bash
.venv/bin/python -m zipfile -l dist/*.whl | grep data
```

Smoke-test the built wheel in a throwaway environment:

```bash
python3 -m venv /tmp/check
/tmp/check/bin/python -m pip install dist/*.whl
/tmp/check/bin/python -c "import my_hello_world_sample as m; print(m.hello()); print(m.list_entries())"
```

## Publishing to PyPI

**Before your first upload, edit these two placeholders:**

- `authors` in `pyproject.toml` — PyPI rejects uploads without an author name
  and email.
- `__version__` in `src/my_hello_world_sample/__init__.py` — the version is
  read from there, so this is the only place to bump it. It cannot be reused
  once published; bump it for every release.

Then:

```bash
.venv/bin/python -m build
.venv/bin/python -m twine check dist/*
```

Try [TestPyPI](https://test.pypi.org) first — it accepts uploads of the same
name you plan to use on real PyPI:

```bash
.venv/bin/python -m twine upload --repository testpypi dist/*
```

Upload to real PyPI:

```bash
.venv/bin/python -m twine upload dist/*
```

`twine` will prompt for your PyPI username and an API token. Create one at
<https://pypi.org/manage/account/token/> — scope it to this project only.

## License

MIT — see [LICENSE](LICENSE).
