mullion 0.1.0__tar.gz

mullion-0.1.0/.github/ISSUE_TEMPLATE/01-defect.yml

@@ -0,0 +1,50 @@
+name: Defect
+description: An image comes out wrong, or a documented behaviour is not the behaviour.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Every defect this library addresses is silent — a wrong answer renders
+        as a *plausible picture*. So the input is the report. Without it there
+        is nothing to reproduce, because every implementation in this space
+        produces a plausible picture for some input and the whole question is
+        which one.
+  - type: textarea
+    id: input
+    attributes:
+      label: The input
+      description: >-
+        Attach the file, or paste the code that builds it. A constructing
+        snippet is often better than a file — see tests/conftest.py, where
+        every fixture is built that way so a reader can see what makes it
+        awkward.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: call
+    attributes:
+      label: The call you made
+      description: The exact call, with its arguments.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected, and what you got
+      description: >-
+        Pixel values beat adjectives. `image.getpixel((0, 0))` returning
+        `(0, 0, 0)` where you wanted `(255, 255, 255)` is a report that can be
+        turned into a test in one step; "the background looks wrong" is not.
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: Mullion, Pillow and Python.
+      placeholder: "mullion 0.1.0, Pillow 12.3.0, Python 3.13"
+    validations:
+      required: true

mullion-0.1.0/.github/ISSUE_TEMPLATE/02-change.yml

@@ -0,0 +1,47 @@
+name: Change
+description: You want Mullion to do something it does not.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Please read [what is out of
+        scope](https://github.com/sigrix-io/mullion#what-it-is-not) first.
+        The scope is narrow on purpose and a change that widens it will be
+        turned down however good it is — an application takes this library on
+        because it is small.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What goes wrong today
+      description: >-
+        Describe the situation, not the feature. The most useful reports here
+        are "an image arrived in a shape you do not handle and was silently
+        accepted", which is the thesis of the whole library.
+    validations:
+      required: true
+  - type: textarea
+    id: workaround
+    attributes:
+      label: What you do instead right now
+      description: >-
+        If the answer is a few lines of Pillow in your own codebase, paste
+        them. That is the strongest possible case: it is what every caller
+        would otherwise be writing separately, which is exactly the argument
+        for it living here.
+      render: python
+    validations:
+      required: false
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Does this handle one image, or several?
+      description: >-
+        The line is stated in the README and CONTRIBUTING: this library handles
+        one image, and composing several is the application's job.
+      options:
+        - One image
+        - Several images
+        - Not sure
+    validations:
+      required: true

mullion-0.1.0/.github/ISSUE_TEMPLATE/03-depend.yml

@@ -0,0 +1,41 @@
+name: I depend on this
+description: Not a defect. Tell us you are building on 0.x so we do not break you silently.
+labels: ["dependent"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        [VERSIONING.md](https://github.com/sigrix-io/mullion/blob/main/VERSIONING.md)
+        says plainly that any `0.x` release may break any other. This form is
+        the other half of that bargain: the practical difference between an
+        announced breaking change and a surprising one is knowing somebody is
+        out there.
+  - type: input
+    id: version
+    attributes:
+      label: Which version are you pinned to?
+      placeholder: "mullion~=0.1.0"
+    validations:
+      required: true
+  - type: checkboxes
+    id: surface
+    attributes:
+      label: Which parts do you use?
+      description: >-
+        This is what tells us which change would actually cost you something.
+      options:
+        - label: "`normalize` / `open_bytes` / `open_path`"
+        - label: "`clean_background` and its defaults"
+        - label: "`page` geometry and DPI"
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else worth knowing
+      description: >-
+        What you are building, whether you have pinned the defaults, whether a
+        change in *output* would be a problem for you or merely a diff. No
+        obligation to name your project.
+    validations:
+      required: false

mullion-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,23 @@
+# The three forms alongside this file are the three kinds CONTRIBUTING.md says
+# are triaged differently. A blank issue would let the classification be
+# skipped, which is the thing that does not currently work.
+blank_issues_enabled: false
+
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/sigrix-io/mullion/security/policy
+    about: >-
+      Do not open a public issue. Email security@sigrix.io — acknowledged
+      within 72 hours. This library decodes untrusted bytes; an input that
+      makes it misbehave is in scope.
+  - name: Raise a code of conduct concern
+    url: https://github.com/sigrix-io/mullion/blob/main/CODE_OF_CONDUCT.md
+    about: >-
+      Email conduct@sigrix.io. A different address and a different queue from
+      security reports; neither is a fallback for the other.
+  - name: A bug in Pillow itself
+    url: https://github.com/python-pillow/Pillow/issues
+    about: >-
+      Mullion is a thin layer over Pillow. If the wrong answer is Pillow's,
+      report it there — unless something here makes it worse or reachable, in
+      which case file a defect and say so.

mullion-0.1.0/.github/dependabot.yml

@@ -0,0 +1,37 @@
+# Keeps the two things this repository pins from ageing quietly.
+#
+# The ruff version in ci.yml is pinned so that a local `ruff format` and the CI
+# check can never disagree. That trade has a second half which is easy to leave
+# unbuilt: a pin only stays correct if something bumps it, and left alone the
+# formatter drifts away from whatever contributors have installed — the same
+# failure pinning exists to prevent, arriving from the other direction and with
+# a green check the whole way.
+#
+# The test matrix is what makes this safe rather than merely automatic. A bump
+# that breaks anything arrives as a red check on a pull request nobody has
+# merged, and because `ci-passed` is required on `main`, it cannot land without
+# passing.
+#
+# Two GitHub behaviours worth knowing: this file is read from the default
+# branch, so editing it on a branch changes nothing until it merges; and
+# Dependabot needs the dependency graph enabled on the repository, which is not
+# something this file can assert.
+#
+# Deliberately no auto-merge. Whether these should merge themselves when green
+# is a judgement about how much unattended merging is wanted, and it belongs on
+# the record rather than defaulted into by a config nobody revisits.
+version: 2
+updates:
+  # Both the runtime floor and the dev extras.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  # Turns an action deprecation into a pull request, rather than a warning at
+  # the top of a log nobody reads until the runtime is withdrawn and checkout
+  # starts failing on whichever pull request happens to be open that day.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

mullion-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,37 @@
+## What this changes
+
+<!-- One or two sentences. The diff shows what changed; say why. -->
+
+## Does it change output?
+
+<!--
+The question that matters most in a library that produces pixels. Delete the
+rows that do not apply.
+
+- [ ] No — refactor, docs, tests or tooling only.
+- [ ] Yes, and it is a fix — the previous output was wrong. Say for which
+      inputs, so the changelog entry can name them.
+- [ ] Yes, and it is a default moving. CONTRIBUTING asks for the images:
+      what got better, and what got worse. There is no threshold that is right
+      for everything.
+-->
+
+## Have you watched the new tests fail?
+
+<!--
+CONTRIBUTING calls this the one house rule. Every defect this library addresses
+is silent, so a test can assert the right thing about the right pixel and still
+be worthless — break the implementation deliberately, confirm the test that
+names the claim goes red, then put it back.
+
+Say which mutation you tried and which test caught it.
+-->
+
+## Checks
+
+- [ ] `python -m pytest`
+- [ ] `python -m ruff check src/ tests/`
+- [ ] `python -m ruff format --check src/ tests/`
+- [ ] `python -m mypy --strict src/mullion`
+- [ ] Scope: this still handles *one* image (see CONTRIBUTING)
+- [ ] `CHANGELOG.md` updated under `Unreleased`, if this is user-visible

mullion-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+# Lint, then test, then prove the package builds and installs.
+#
+# The ruff steps run before pytest deliberately: a formatting slip should fail
+# the job in ten seconds rather than after the suite. They are two commands
+# rather than one because `check` and `format --check` answer different
+# questions and only one of them is about style.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      # Pinned, so that a local `ruff format` and this check can never disagree
+      # about formatter behaviour. Dependabot bumps it; the tests gate the bump.
+      - run: python -m pip install ruff==0.16.5
+      - run: python -m ruff check src/ tests/
+      - run: python -m ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest
+
+  # ``py.typed`` ships in the wheel and pyproject declares ``Typing :: Typed``,
+  # which together tell every consumer's type checker to trust these
+  # annotations instead of treating the package as untyped. Nothing verified
+  # them until #3, and a wrong annotation is the quietest defect a library can
+  # ship: it does not raise, it just makes somebody else's mypy run confidently
+  # green about the wrong thing. Pinned for the same reason ruff is — a
+  # floating checker turns an unrelated release into a red build on a commit
+  # that changed nothing.
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m mypy --strict src/mullion
+
+  # A floor nobody tests is a guess. pyproject declares pillow>=10.0, so
+  # something has to actually run against 10.0 — otherwise the first user on an
+  # older Pillow discovers the real floor for us, in production.
+  oldest-pillow:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pip install "pillow==10.0.*"
+      - run: python -m pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install build twine
+      - run: python -m build
+      # Catches a README that renders on GitHub and not on PyPI, which is
+      # otherwise found at the moment of publishing and not before.
+      - run: python -m twine check dist/*
+      # The wheel is what users get. Installing it from a clean directory is
+      # the only thing that proves py.typed and the package layout shipped —
+      # an editable install reads the source tree and would pass either way.
+      - name: The built wheel imports and carries its type marker
+        run: |
+          python -m venv /tmp/wheelcheck
+          /tmp/wheelcheck/bin/python -m pip install --quiet dist/*.whl
+          cd /tmp
+          /tmp/wheelcheck/bin/python -c "
+          import mullion, pathlib
+          print('version', mullion.__version__)
+          root = pathlib.Path(mullion.__file__).parent
+          assert (root / 'py.typed').exists(), 'py.typed did not ship'
+          for name in mullion.__all__:
+              assert hasattr(mullion, name), name
+          print(len(mullion.__all__), 'exports resolve')
+          "
+
+  # The aggregate gate. One check to require on main, so adding a job above
+  # does not mean editing a branch protection rule to match.
+  ci-passed:
+    if: always()
+    needs: [lint, types, test, oldest-pillow, build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Every job succeeded
+        run: |
+          echo '${{ toJSON(needs) }}'
+          [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" = "false" ]

mullion-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,148 @@
+# Publish a tagged release to PyPI. Nothing else in this repository publishes,
+# and nothing in this file runs on a branch — a release is a tag, deliberately,
+# so that publishing is an act with a name rather than a side effect of a merge.
+#
+# Trusted publishing (OIDC) rather than an API token: the runner exchanges a
+# short-lived identity for an upload, so there is no long-lived secret in this
+# repository to store, leak or rotate. The trade is that PyPI has to be told
+# which workflow in which environment it trusts, which is configuration that
+# lives there and not here — see the note on `environment:` below.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+# Read-only by default. Only the publish job widens this, and only to the one
+# permission the OIDC exchange needs.
+permissions:
+  contents: read
+
+# Deliberately NOT `cancel-in-progress`, which is what ci.yml sets. Cancelling
+# a CI run wastes a runner; cancelling a run that is mid-upload can leave a
+# release half-landed, and a PyPI version number can never be reused — not even
+# after deleting the file. There is nothing to gain here by being fast.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # Everything that can say no, said before anything leaves the runner.
+  build:
+    runs-on: ubuntu-latest
+    # A fork can push a tag to itself; it must not be able to build the
+    # artifacts this repository's trust policy would then be asked to publish.
+    if: github.repository == 'sigrix-io/mullion'
+    steps:
+      # checkout and setup-python track ci.yml's pins on purpose, rather than
+      # the newest majors: this workflow runs once per release, at the moment
+      # when discovering an action's breaking change is most expensive, so it
+      # should run on the versions the rest of the repository has exercised.
+      # Dependabot moves both files together.
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - run: python -m pip install build twine
+      - run: python -m build
+
+      # hatchling reads the version out of pyproject.toml; the tag is typed by
+      # hand. Nothing makes them agree. Tagging v0.2.0 without bumping
+      # pyproject builds 0.1.0 and would publish it under a tag saying
+      # otherwise — or, if 0.1.0 is already on PyPI, fail at the upload with a
+      # duplicate-file error naming neither cause. Ask here instead, where the
+      # answer is still cheap.
+      - name: The tag names the version that was actually built
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          # mullion-0.1.0-py3-none-any.whl -> 0.1.0. A wheel filename uses "-"
+          # as its field separator, so a PEP 440 version can never contain one.
+          built="$(basename "$(ls dist/*.whl)" | cut -d- -f2)"
+          echo "tag=${tag}  built=${built}"
+          if [ "${tag}" != "${built}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not name the packaged version ${built}. Bump pyproject.toml, or delete the tag and retag."
+            exit 1
+          fi
+
+      # A release nobody wrote down is one a dependent cannot evaluate, which
+      # is the whole promise VERSIONING.md makes while this is 0.x. Keep a
+      # Changelog puts the version in a heading, so this is an exact check
+      # rather than a guess at prose.
+      - name: The changelog has an entry for this version
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#v}"
+          if ! grep -qF "## [${version}]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no '## [${version}]' heading. Move the Unreleased entries under it before tagging."
+            exit 1
+          fi
+
+      # Catches a README that renders on GitHub and not on PyPI, which is
+      # otherwise found at the moment of publishing and not before.
+      - run: python -m twine check dist/*
+
+      # ci.yml proves the *source tree* passes, via an editable install. This
+      # proves the *artifact* does, which is a different question and the only
+      # one that still matters once the bytes are immutable on PyPI: a file
+      # missing from the wheel is invisible to every editable-install run.
+      - name: The built wheel installs, imports, and passes the suite
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/releasecheck
+          /tmp/releasecheck/bin/python -m pip install --quiet dist/*.whl pytest
+          # From /tmp, so nothing in the checkout can satisfy the import.
+          cd /tmp
+          /tmp/releasecheck/bin/python -c "
+          import mullion, pathlib
+          root = pathlib.Path(mullion.__file__).parent
+          assert (root / 'py.typed').exists(), 'py.typed did not ship'
+          for name in mullion.__all__:
+              assert hasattr(mullion, name), name
+          print(mullion.__version__, '-', len(mullion.__all__), 'exports resolve')
+          "
+          cd "${GITHUB_WORKSPACE}"
+          # src-layout means ./mullion does not exist, so the import below can
+          # only resolve to the wheel in the venv. Asserted rather than assumed:
+          # a suite that quietly re-tested the source tree would look identical.
+          /tmp/releasecheck/bin/python -c "
+          import mullion
+          assert 'site-packages' in mullion.__file__, mullion.__file__
+          "
+          /tmp/releasecheck/bin/python -m pytest tests/
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # Separate from the build so that a failure above cannot half-publish: this
+  # job does not start unless every check passed, and it builds nothing itself.
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      # PyPI's trusted-publisher policy names this environment alongside the
+      # repository and the workflow filename, so the three have to match what
+      # is configured there. It is also where to add a required reviewer if a
+      # release should ever need a second pair of eyes.
+      name: pypi
+      url: https://pypi.org/p/mullion
+    permissions:
+      # The only elevated permission in this file, scoped to the one job that
+      # needs it. This mints the OIDC token PyPI exchanges for an upload, and
+      # it is also what makes the action attach PEP 740 attestations.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      # Pinned to the commit rather than the tag. A tag is mutable by whoever
+      # owns the action, and this is the one step in this repository holding a
+      # credential worth stealing. Dependabot bumps the pin and rewrites the
+      # trailing comment with it.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

mullion-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python bytecode. CONTRIBUTING.md asks every contributor to run pytest and
+# ruff before pushing, so these appear during a normal contribution rather than
+# only on a maintainer's machine. Without this entry one routine `git add -A`
+# commits build artefacts nobody wants to review.
+__pycache__/
+*.py[cod]
+
+# An editable install writes here, and `python -m build` writes the other two.
+*.egg-info/
+build/
+dist/
+
+# Installing without touching the system Python means a virtual environment.
+# Both conventional names are listed so whichever a contributor reaches for
+# stays untracked.
+.venv/
+venv/
+
+# Test and tooling caches.
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/

mullion-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes are recorded here. The format is
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [VERSIONING.md](VERSIONING.md) — read it before pinning, because
+pre-1.0 means what it says.
+
+## [Unreleased]
+
+### Fixed
+
+- The annotations `py.typed` promises are now verified. The wheel ships
+  `src/mullion/py.typed` and the package declares `Typing :: Typed`, which
+  together tell a consumer's type checker to trust these annotations — but
+  nothing had ever run one, and `mypy --strict` reported nine errors on the
+  first release. All nine were `Image.load()`, typed `PixelAccess | None` and
+  indexed without narrowing. Nothing raised: a wrong annotation just makes
+  somebody else's type checker confidently green about the wrong thing.
+  ([#3](https://github.com/sigrix-io/mullion/issues/3))
+
+### Changed
+
+- `mullion.background`'s two internal pixel readers now assert the image mode
+  they were written for instead of assuming it, so a caller handing one the
+  wrong mode fails immediately rather than reading a shape nothing checks.
+  No public API changed.
+
+## [0.1.0]
+
+First release.
+
+### Added
+
+- `mullion.source` — `normalize()`, and the `open_bytes()` / `open_path()`
+  adapters over it. Applies the EXIF orientation tag and resolves transparency
+  in all three shapes it arrives in: `RGBA`, `LA`, and palette `P` carrying a
+  `transparency` key in `info`. `keep_alpha` chooses between compositing onto a
+  matte and preserving the channel.
+- `mullion.background` — `clean_background()`, border-seeded so that a
+  near-white region enclosed by the subject is never mistaken for the
+  background around it. `looks_like_white_background()` answers the same
+  verdict without doing the work, and `keeps_alpha()` names the one coupling
+  between the open call and the clean call.
+- `mullion.page` — `resolve_page_geometry()` and `named_page_geometry()`,
+  returning pixels and the DPI they were derived at as one value.

mullion-0.1.0/CODEOWNERS

@@ -0,0 +1,25 @@
+# Every change to this repository requires review from a maintainer.
+#
+# Merging is discretionary and stays with the maintainers — see
+# CONTRIBUTING.md. Contributions are welcome; governance is not open.
+#
+# The owner is a team rather than a person so that reviewer load can be shared
+# without editing this file for every change in personnel, and so the
+# repository does not advertise a single point of failure to anyone deciding
+# whether to depend on it. It may hold one person; the indirection is the point.
+
+*                       @sigrix-io/mullion-maintainers
+
+# The published surface. Everything under src/ is a compatibility commitment
+# the moment someone pins to a release, so it is called out separately from the
+# repository default even though the owner is currently the same.
+#
+# tests/ belongs here for a reason worth stating: the defects this library
+# exists for are silent — a wrong answer renders as a plausible picture — so
+# the tests are the only thing that can see them. A weakened test is a
+# weakened guarantee, arriving as a green run.
+
+/src/                   @sigrix-io/mullion-maintainers
+/tests/                 @sigrix-io/mullion-maintainers
+/pyproject.toml         @sigrix-io/mullion-maintainers
+/VERSIONING.md          @sigrix-io/mullion-maintainers