python-mla 0.1.0

No project description provided

python-mla

A Python package for generating MLA 9-style website citations from webpage metadata.

python-mla fetches a webpage, reads its HTML metadata, and formats the result as an MLA-style citation. If metadata is incomplete, it can optionally use the OpenAI API to infer missing fields.

Features

• Generate MLA 9-style citations from a webpage URL
• Extract common metadata fields automatically
• Supports:
  • author
  • title
  • website name
  • publication date
  • publisher fallback
• Optional AI fallback for incomplete metadata
• Simple Python API
• Tested with pytest

Installation

Install with Poetry:

poetry add python-mla

Or with pip:

pip install python-mla

Requirements

• Python 3.12+
• Internet connection for webpage fetching
• OpenAI API key only if using allow_ai=True

Basic Usage

from python_mla import website_mla

citation = website_mla("https://example.com/article")
print(citation)

Example output:

Smith, John. "Example Article." Example Site, 15 Jan. 2024, example.com/article.

AI Fallback Usage

If a webpage is missing some metadata, you can enable AI fallback:

from python_mla import website_mla

citation = website_mla(
    "https://example.com/article",
    allow_ai=True,
    openai_api_key="your-api-key-here",
)

print(citation)

API

website_mla(url, allow_ai=False, openai_api_key=None)

Generate an MLA 9-style citation for a webpage.

Parameters

• url (str): The webpage URL to cite
• allow_ai (bool): Whether to use AI to infer missing citation data
• openai_api_key (str | None): OpenAI API key used when AI fallback is enabled

Returns

• str: A formatted MLA-style citation string

Raises

• APIKeyError: If allow_ai=True but no valid OpenAI API key is provided
• requests.HTTPError: If the webpage request fails

Example

from python_mla import website_mla

citation = website_mla("https://www.example.com/news/story")
print(citation)

Possible output:

Doe, Jane. "Breaking News Story." Example News, 05 Feb. 2025, www.example.com/news/story.

How It Works

1. Sends a request to the webpage URL
2. Parses the HTML using BeautifulSoup
3. Looks for citation-related metadata in common meta tags
4. Formats the result into an MLA-style citation
5. Optionally uses AI if important fields are missing

Notes

• Citation quality depends on the quality of the webpage metadata
• Some websites do not provide complete or consistent metadata
• AI fallback may improve incomplete citations, but results can vary
• This package currently focuses on webpage citations, not books, journals, or videos

Development

Clone the repo and install dependencies:

poetry install

Run tests:

poetry run pytest

Build the package:

poetry build

Project Structure

python_mla/
├── pyproject.toml
├── README.md
├── LICENSE
├── python_mla/
│   ├── __init__.py
│   └── main.py
└── tests/
    └── test_main.py

Public API

from python_mla import website_mla, APIKeyError

Limitations

• Only supports website MLA citations right now
• Metadata extraction is limited to common HTML meta fields
• Some author formats may still be imperfect
• AI fallback requires an OpenAI API key and network access

Roadmap

Potential future improvements:

• Better metadata fallback support
• Support for more meta tag standards
• Structured return data in addition to citation strings
• Support for other citation styles
• Support for more source types

License

MIT License