Welcome to imitation-game

CI CD Docs codecov Python Version TestPyPI PEP8

imitation-game is a Python utility package for secure message processing. It provides a high-level interface for both Symmetric (shared secret) and Asymmetric (Public/Private key) encryption.

Symmetric Encryption Fast and efficient encryption using a single shared key. Best for internal data storage or pre-shared secrets.

  • generate_symmetric_key: Creates a cryptographically secure random key.
  • encrypt_symmetric: Encrypts a plaintext message using a symmetric key.
  • decrypt_symmetric: Restores an encrypted message back to plaintext using the same key.

Asymmetric Encryption (RSA) Secure communication between two parties without needing to share a secret key beforehand. Uses sender/receiver key combinations where the sender encrypts with the receiver’s public key AND signs with their own private key. This provides both confidentiality (only receiver can decrypt) and authenticity (receiver can verify the sender’s identity), similar to PGP encryption.

  • generate_asymmetric_key: Generates a pair of RSA keys: a Public Key (for encryption/verification) and a Private Key (for decryption/signing).
  • encrypt_asymmetric: Encrypts a message using the receiver’s public key and signs it with the sender’s private key. Takes parameters: (message, receiver_public_key, sender_private_key).
  • decrypt_asymmetric: Decrypts a message using the receiver’s private key and verifies the sender’s signature using the sender’s public key. Takes parameters: (encrypted_data, receiver_private_key, sender_public_key).

Comparison with the Python Ecosystem

There are many message encoding and decoding related packages on the PyPI server. We have selected a few key examples that with similar functionality as our package.

  • Cipher-symmetric: Focuses exclusively on symmetric string encryption, acting as a high-level wrapper for the cryptography module.
  • Encryption: A broad educational tool demonstrating AES, RSA, and hashing via pycryptodome. It is comprehensive but often requires more boilerplate code to implement.
  • encrypt_data: Specializes in Hybrid Encryption, which uses asymmetric keys to securely exchange symmetric keys.

While the packages above are powerful, they often cater to either a single encryption style or require deep cryptographic knowledge to configure properly. The primary benefit of imitation-game is its focus on a unified, high-level API that abstracts away the complexity of both symmetric and asymmetric workflows.

Installation

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ imitation-game

Dependencies: - pycryptodome - Cryptographic operations - pathvalidate - File path validation

Test PyPI: https://test.pypi.org/project/imitation_game

Usage Examples

Symmetric Key Generation

Note: All outputted keys will vary on uses of generate_symmetric_key and generate_asymmetric_key.

>>> from imitation_game import generate_symmetric_key

>>> # Generate a secure random key for symmetric encryption
>>> key = generate_symmetric_key() # Returns: 32-byte key (e.g., b'\x8f\x9a\x1b...')
>>> print(f"Generated key: {key[:10]}...")  # Shows first 10 characters
Generated key: Vy7K5usqcE...

# Save the key keys/my_encryption_key.txt for later use
>>> key = generate_symmetric_key("keys/my_encryption_key.txt")

Symmetric Encryption

>>> from imitation_game import generate_symmetric_key, encrypt_symmetric, decrypt_symmetric

# Generate key 
>>> key = generate_symmetric_key()

# Encrypts and decrypts message with key
>>> message = "Secret message"
>>> encrypted_data = encrypt_symmetric(message, key)
>>> print(f"Encrypted: {encrypted_data[:20]}...")
Encrypted: 6k8HkEQUosOXaOFGW1hq...
>>> decrypted_message = decrypt_symmetric(encrypted_data, key)
>>> print(decrypted_message) 
Secret message

Asymmetric Encryption (Sender/Receiver)

>>> from imitation_game import generate_asymmetric_key, encrypt_asymmetric, decrypt_asymmetric

# Generate key pairs for sender and receiver
# NOTE: Printed output has been shortened for ease of this README.
# The function will print out the full keys.
>>> sender_private, sender_public = generate_asymmetric_key()
PRIVATE KEY:

b'-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAK......V8WZ5NRcY=\n-----END RSA PRIVATE KEY-----'
PUBLIC KEY:

b'-----BEGIN PUBLIC KEY-----\nMIIBIjANBg......L4\n8wIDAQAB\n-----END PUBLIC KEY-----'

>>> receiver_private, receiver_public = generate_asymmetric_key()
PRIVATE KEY:

b'-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAK......azpF3S3lzNWJ\n-----END RSA PRIVATE KEY-----'
PUBLIC KEY:

b'-----BEGIN PUBLIC KEY-----\nMIIBIjANBg......T8G\nowIDAQAB\n-----END PUBLIC KEY-----'

# Sender encrypts message with receiver's public key and signs with their private key
>>> message = "Secret message"
>>> encrypted_data = encrypt_asymmetric(message, receiver_public, sender_private)
>>> print(f"Encrypted data length: {len(encrypted_data)} bytes")
Encrypted data length: 512 bytes

# Receiver decrypts with their private key and verifies sender's signature
>>> decrypted_message = decrypt_asymmetric(encrypted_data, receiver_private, sender_public)
>>> print(decrypted_message)
Secret message

Development

Setting Up the Development Environment

This project uses conda for environment management, but dependencies are defined in pyproject.toml. Follow these steps to set up your development environment:

  1. Create a conda environment with Python 3.10 or higher:

    conda create -n imitation-game python=3.12
conda activate imitation-game

    Alternatively, use the provided environment.yml file:

    conda env create -f environment.yml
conda activate imitation-game

  2. Install the package in editable mode with all development dependencies:

    # Clone the repository
git clone https://github.com/UBC-MDS/imitation_game.git
cd imitation_game

# Install the package with all optional dependencies (dev, docs, tests, build)
pip install -e ".[dev,docs,tests,build]"

    This will install:

    • The package itself in editable mode
    • Development tools: hatch, pre-commit
    • Documentation tools: quartodoc
    • Testing tools: pytest, pytest-cov, pytest-raises, pytest-randomly, pytest-xdist, flake8-pyproject
    • Build tools: pip-audit, twine

Running Tests

Tests are located in the tests/ directory and can be run using pytest:

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=imitation_game --cov-report=term-missing

# Run tests using hatch (recommended)
hatch run +py=3.12 test:run

The test suite includes both unit tests (tests/unit/) and integration tests (tests/integration/).

Building Documentation

Documentation is built using Quarto and quartodoc. To build the documentation locally:

  1. Ensure Quarto is installed:

  2. Build the documentation:

    # Generate API reference documentation
quartodoc build

# Render the Quarto website
quarto render

  3. Preview the documentation locally:

    quarto preview

The documentation will be generated in the _site/ directory (or similar, depending on your Quarto configuration).

Automated Documentation Deployment

Documentation is automatically built and deployed to GitHub Pages when: - Changes are pushed to the main branch - The workflow is manually triggered via GitHub Actions

The deployment workflow (.github/workflows/docs.yml) handles: - Building the Quarto documentation - Publishing to the gh-pages branch - Making the documentation available at the repository’s GitHub Pages URL

No manual intervention is required for documentation deployment once changes are merged to main. Documentation is deployed here

PR deployment previews

Pull requests get an automatic documentation preview so you can see how the docs will look before merging. The preview is built by .github/workflows/docs.yml and deployed to Netlify; a comment with the preview URL is posted on each PR.

Every new PR will get a Netlify deploy preview and a comment with the preview link.

CI/CD Pipeline

We use GitHub Actions for continuous integration and deployment: - Tests: Run automatically on every push and pull request via build.yml - Deploy: Automatically deploys to TestPyPI when changes are pushed to main via deploy.yml - Docs: Documentation is built and deployed to GitHub Pages on every push via docs.yml - Docs preview: Each pull request gets a documentation preview deployed to Netlify via docs.yml (requires Netlify secrets; see above)

Contributing

For information about how to contribute to this package, please review our Contributing document. All contributors must abide by our Code of Conduct

License

This packages uses the MIT License, more information can be found here alongside reasoning for this license here.

Citation

If you use this package in your research or project, please cite it as:

@software{imitation_game2026,
  author = {Valson, Vinay and Joshi, Tirth and Kwong, Teem and Wen, Alexander},
  title = {imitation-game: A Python Package for Secure Message Encryption},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/UBC-MDS/imitation_game}
}

APA Style: Valson, V., Joshi, T., Kwong, T., & Wen, A. (2026). imitation-game: A Python Package for Secure Message Encryption [Computer software]. GitHub. https://github.com/UBC-MDS/imitation_game

References

This package implements cryptographic operations based on established standards and best practices:

Cryptographic Standards

Security Best Practices

Python Cryptography Libraries

Credits

This package imitation-game is created with [pyOpenSci copier template] (https://github.com/pyOpenSci/pyos-package-template)

Contributors

Vinay Valson

  • Affiliation: University of British Columbia
  • GitHub: @Vin-dictive

Tirth Joshi

  • Affiliation: University of British Columbia
  • GitHub: @tirthjoship

Teem Kwong

  • Affiliation: University of British Columbia
  • GitHub: @mdskwong

Alexander Wen

  • Affiliation: University of British Columbia
  • GitHub: @alxwen711