fake.py: Instructions file for Codex

AGENTS.md — fake.py

Repository: https://github.com/barseghyanartur/fake.py Maintainer: Artur Barseghyan [email protected]

This file is for AI agents and developers using AI assistants to work on or with fake.py. It covers two distinct roles: using the package in application code, and developing/extending the package itself.

---

1. Project Mission (Never Deviate)

Minimalistic, standalone fake data generator with no dependencies.

• Generates fake data for testing and development
• Zero runtime dependencies (only optional dependencies for testing, development, documentation and building)
• Single-file architecture with self-contained providers
• Random texts, (person) names, emails, URLs, dates, IPs, and primitive Python data types
• GEO data (city, country, geo-location, country code, latitude, longitude, locales)
• IBANs and ISBNs
• File formats (PDF, DOCX, ODT, RTF, EPUB, TXT, PNG, SVG, BMP, GIF, TIF, PPM, JPG, WAV, ZIP, TAR, EML)
• StringTemplate and LazyStringTemplate for dynamic content generation
• FILE_REGISTRY for tracking and cleanup of generated files
• CLI for generating data from command line
• Factories (dynamic fixtures) for Django, Pydantic, TortoiseORM, and SQLAlchemy

---

2. Using fake.py in Application Code

Simple case

from fake import FAKER

name = FAKER.name()
email = FAKER.email()
text = FAKER.text()

assert name  # "John Doe"
assert email  # "[email protected]"
assert text  # Paragraph of lorem ipsum

File generation

from fake import FAKER, FILE_REGISTRY

txt_file = FAKER.txt_file()
docx_file = FAKER.docx_file(nb_pages=2)
pdf_file = FAKER.pdf_file(nb_pages=5)
zip_archive = FAKER.zip_file(options={"count": 10})

assert txt_file
assert docx_file
assert pdf_file
assert zip_archive

FILE_REGISTRY.clean_up()  # Remove generated files

StringTemplate for static content

from fake import FAKER, StringTemplate

template = StringTemplate("""
    Date: {date}
    To: {name}
    Subject: {sentence(nb_words=8)}
""")
result = str(template)
assert result
assert "Date:" in result
assert "To:" in result