PyPI version

Pygfried

pygfried is a CPython extension that brings siegfried - a powerful, signature-based file format identification tool written in Go - into the Python ecosystem.

Identifying a file with pygfried

Instead of reimplementing siegfried's logic, pygfried embeds the original Go code directly, making core siegfried functionality available to Python users without any changes to the underlying detection engine.

No animals were harmed in the making of this extension.

Usage

$ pip install pygfried
$ python -q
>>> import pygfried
>>> pygfried.version()
'1.11.6'
>>> pygfried.identify("example.png")
'fmt/11'
>>> pygfried.identify("example.png", detailed=True)
{'siegfried': '1.11.6', 'scandate': '2025-06-10T07:16:31+02:00', 'signature': 'default.sig', 'created': '2025-03-01T15:28:08+11:00', 'identifiers': [{'name': 'pronom', 'details': 'DROID_SignatureFile_V124.xml; container-signature-20260119.xml'}], 'files': [{'filename': 'example.png', 'filesize': 237675, 'modified': '2025-06-10T07:11:26+02:00', 'errors': '', 'matches': [{'ns': 'pronom', 'id': 'fmt/11', 'format': 'Portable Network Graphics', 'version': '1.0', 'mime': 'image/png', 'class': 'Image (Raster)', 'basis': 'extension match png; byte match at [[0 16] [237663 12]]', 'warning': ''}]}]}
>>> pygfried.identify_many(["example.png", "README.md"], workers=2)
{'siegfried': '1.11.6', ...}
>>> pygfried.identify_dir("samples", recursive=True, workers=2)
{'siegfried': '1.11.6', ...}

The module-level functions always use Siegfried's embedded default.sig. Use a Scanner when you need another signature database:

import pygfried

scanner = pygfried.Scanner(profile="archivematica")
scanner.identify("disk-image.ad1")
# 'archivematica-fmt/2'

result = scanner.identify("disk-image.ad1", detailed=True)
assert result["signature"] == "archivematica.sig"

Available bundled profiles are:

  • default, which is also selected by Scanner() and matches the behavior of the module-level functions.
  • archivematica, which contains the complete PRONOM database plus Archivematica's extended identifiers for AD1, encrypted AD1, raw disk images, and AFF.

The Archivematica database is copied from the exact Siegfried module version used to compile pygfried. It is embedded in the extension, so it does not need to be installed separately.

To use another complete Siegfried signature database, pass its path:

scanner = pygfried.Scanner(signature="/usr/share/siegfried/custom.sig")

profile and signature are keyword-only and mutually exclusive. External databases are validated and loaded into memory when the scanner is constructed; changing or deleting the file afterward does not change that scanner. The read-only scanner.profile and scanner.signature properties report the selected source.

Batch and directory scans

Use identify_many when you already have a list of paths, or identify_dir when you want pygfried to scan a directory for you. Both functions return the same detailed result shape as identify(..., detailed=True).

>>> from pathlib import Path
>>> paths = [str(path) for path in Path("samples").rglob("*.png")]
>>> pygfried.identify_many(paths, workers=4)
{'siegfried': '1.11.6', ...}
>>> pygfried.identify_dir("samples", recursive=True, workers=4)
{'siegfried': '1.11.6', ...}

The workers argument controls Go-side concurrency. The default is 1, which is the most conservative setting. For directories or large path lists, higher values can be much faster because pygfried avoids repeated Python-to-Go calls and identifies multiple files in parallel. A good starting point is the number of CPU cores available to your process, then measure with your own files.

By default identify_dir skips symlinks. Use follow_symlinks=True to identify file symlinks and descend symlinked directories; directory cycles are skipped, and repeated links to the same directory are scanned once.

Concurrency

A Scanner is safe to reuse across threads. Each scanner owns an independent, immutable Siegfried engine, while each identify_many or identify_dir call controls its own Go-side concurrency with workers. There is no process-wide worker limit beyond the per-call range of 1 to 1024.

Create scanners after a process forks rather than attempting to serialize or transfer them between processes.

Limitations

Go libraries can clash

This project uses Go's -buildmode=c-shared to provide its Python extension. Loading multiple Go-based shared libraries in the same process is unsupported and may result in panics or crashes due to conflicts between separate Go runtimes.

This limitation should only affect you if you're using pygfried together with another Python library that also uses a Go extension (built with the same c-shared mechanism) in the same process. If you're just using pygfried on its own, you don't need to worry - everything should work as expected.

Credits

pygfried is powered by the original siegfried project, which is distributed under the Apache License, Version 2.0. All core file format identification logic and signatures are provided by siegfried. We gratefully acknowledge the work of the siegfried project and its contributors.

Project links

Data verified by PyPI on Jul 27, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

3 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for jhsimpson from gravatar.com jhsimpson Avatar for replaceafill from gravatar.com replaceafill Avatar for sevein from gravatar.com sevein

Credits

Author: Artefactual Systems Inc.

GitHub Statistics

Data verified by PyPI on Jul 27, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pygfried-0.17.0.tar.gz (894.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pygfried-0.17.0-cp310-abi3-win_amd64.whl (2.7 MB view details)

Uploaded CPython 3.10+Windows x86-64

pygfried-0.17.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl (2.5 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

pygfried-0.17.0-cp310-abi3-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64manylinux: glibc 2.5+ x86-64

pygfried-0.17.0-cp310-abi3-macosx_11_0_universal2.whl (2.4 MB view details)

Uploaded CPython 3.10+macOS 11.0+ universal2 (ARM64, x86-64)

File details

Details for the file pygfried-0.17.0.tar.gz.

File metadata

  • Download URL: pygfried-0.17.0.tar.gz
  • Upload date:
  • Size: 894.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pygfried-0.17.0.tar.gz
Algorithm Hash digest
SHA256 f2f99d770dace70df98c44dfe86584c6c446e6a876eeab351c8c5f8216486c47
MD5 0adee91114ac4dd66d7fa98460220e71
BLAKE2b-256 c1abde8246770879f7fa6d01113fd4e36919dc90ed4d29f09136cc8cc4d93075

See more details on using hashes here.

Provenance

The following attestation bundles were made for pygfried-0.17.0.tar.gz:

Publisher: release.yml on artefactual-labs/pygfried

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pygfried-0.17.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: pygfried-0.17.0-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 2.7 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pygfried-0.17.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 3102bb9a18a60cbe6640bf56668a4d9a2d1ff904b863b0e1161bed4cae8cb27e
MD5 b2a167d59c4ffbddae142dc6fbde3e6a
BLAKE2b-256 091ad514dfadcf23fcd1623ca29f632c2e871da9e0596ef7c69cfff426a865d5

See more details on using hashes here.

Provenance

The following attestation bundles were made for pygfried-0.17.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on artefactual-labs/pygfried

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pygfried-0.17.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl.

File metadata

File hashes

Hashes for pygfried-0.17.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 70466602ba7f1c79f531084a827e3f892707ec967d39ec652a999d767b289fcb
MD5 73876798560718785103d464ef709860
BLAKE2b-256 fae6b0c904afe1e312343ac39d4567824997296e8fdaa88e5466f16fe706e2d7

See more details on using hashes here.

Provenance

The following attestation bundles were made for pygfried-0.17.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl:

Publisher: release.yml on artefactual-labs/pygfried

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pygfried-0.17.0-cp310-abi3-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for pygfried-0.17.0-cp310-abi3-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 7ac9b474e35c5df36b69878a857403653180d12c2fab3078a0b5ebf4e0eeda6e
MD5 436ac171ba9b833f8673310533b2c987
BLAKE2b-256 6e3d1999965e2c397d7ea46f4f48875fe184bf97e2f3d22d98d9662bf5032f05

See more details on using hashes here.

Provenance

The following attestation bundles were made for pygfried-0.17.0-cp310-abi3-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl:

Publisher: release.yml on artefactual-labs/pygfried

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pygfried-0.17.0-cp310-abi3-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for pygfried-0.17.0-cp310-abi3-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 60654f6863e3b694a3cc2046f5dbdda7f4f4cc7647ebeb455c182df7bf66d73c
MD5 45a5ed15a2421a44aace7deb8471d0fd
BLAKE2b-256 853805dd8f4f860b31b2cd4278662c0760b915b3feb28f87c98c24e42b38f331

See more details on using hashes here.

Provenance

The following attestation bundles were made for pygfried-0.17.0-cp310-abi3-macosx_11_0_universal2.whl:

Publisher: release.yml on artefactual-labs/pygfried

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.17.0 This release

5 files

0.16.1

5 files

0.16.0

5 files

0.15.1

5 files

0.15.0

5 files

0.14.1

5 files

0.14.0

4 files

0.13.0

8 files

0.12.0

8 files

0.11.0

8 files

0.10.0

4 files

0.9.1

3 files

0.9.0

2 files

0.8.0

2 files

0.7.0

3 files

0.6.0

3 files

0.5.0

4 files

0.4.0

4 files

0.3.0

4 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page