FilesInfo

FilesInfo is a Python toolkit for mapping file extensions to rich metadata and recommended execution platforms. It ships with an extensive extension catalog, powerful lookup helpers, and a convenient CLI for exploring the data.

Installation

Clone the repository and install the package in editable mode (or publish to PyPI/TestPyPI and install from there):

pip install .

The installation exposes the filesinfo command-line tool automatically.

Command-Line Usage

# Inspect platform recommendations for file names
filesinfo payload.exe archive.tar.gz

# Output in JSON format for automated systems
filesinfo payload.exe archive.tar.gz --json

# List extensions supported on specific platforms
filesinfo --platform windows --platform linux --include-cross-platform

# Show detailed metadata for each match
filesinfo --platform macos --details

# Review dataset validation warnings
filesinfo --show-dataset-issues

For backwards compatibility the legacy run_demo.py script simply forwards to the same CLI entry point.

Python API Example

from filesinfo import file_info_expert, get_extensions_for_platform

print(file_info_expert("payload.exe"))
# ['windows']

print(get_extensions_for_platform("linux", include_cross_platform=False)[:10])

Developer Commands (Makefile)

For developers contributing to this repository, a Makefile is provided to easily install dev dependencies, run tests, and format code:

make install  # Installs the package with [dev] dependencies
make test     # Runs the unittest suite
make lint     # Runs ruff and black check
make format   # Automatically formats the codebase with ruff and black
make build    # Builds the .tar.gz and .whl packages
make publish  # Uploads the built packages manually to PyPI via twine

Releasing to PyPI

This project is configured with GitHub Actions to automatically publish to PyPI using Trusted Publishing.

To publish a new release:

1. Update the version string in pyproject.toml.
2. Commit and push your changes to GitHub.
3. On GitHub, go to Releases > Draft a new release.
4. Create a new tag (e.g. v0.1.3) and publish the release.

The .github/workflows/publish.yml action will automatically build and upload the package to PyPI without needing any tokens (provided Trusted Publishing is configured in your PyPI project settings).

Updating the Dataset

Regenerate the MIME-driven extension dataset whenever you want the latest upstream metadata:

python3 scripts/update_extension_dataset.py

The command writes a fresh filesinfo/data/external_extensions.json file that is packaged with the library.