Metadata-Version: 2.4
Name: python-mla
Version: 0.1.0
Summary: 
License-File: LICENSE
Author: WillZlog
Author-email: albin.zieme@icloud.com
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: beautifulsoup4 (>=4.12.0,<5.0.0)
Requires-Dist: lxml (>=5.0.0,<6.0.0)
Requires-Dist: openai (>=1.0.0,<2.0.0)
Requires-Dist: requests (>=2.32.0,<3.0.0)
Requires-Dist: titlecase (>=2.4.1,<3.0.0)
Description-Content-Type: text/markdown

# 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:

```bash
poetry add python-mla
```

Or with pip:

```bash
pip install python-mla
```

## Requirements

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

## Basic Usage

```python
from python_mla import website_mla

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

Example output:

```text
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:

```python
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

```python
from python_mla import website_mla

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

Possible output:

```text
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:

```bash
poetry install
```

Run tests:

```bash
poetry run pytest
```

Build the package:

```bash
poetry build
```

## Project Structure

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

## Public API

```python
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

