### Full Configuration Example

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating various configuration options for `[project]` and `[tool.updateCitation]`.

```toml
[project]
name = "mylib"
version = "1.0.0"
description = "A Python library"
authors = [
    { name = "Jane Doe", email = "jane@example.com" }
]
maintainers = [
    { name = "Support", email = "support@example.com" }
]
license = "MIT"
keywords = ["data", "science", "ml"]

[project.urls]
Homepage = "https://mylib.example.com"
Repository = "https://github.com/example/mylib"
License = "https://github.com/example/mylib/blob/main/LICENSE"
Documentation = "https://docs.mylib.example.com"

[tool.updateCitation]
filenameCitationDOTcff = "citation.cff"
pathFilenameCitationSSOT = "citations/CITATION.cff"
addGitHubRelease = true
addPyPIrelease = true
projectURLTargets = ["homepage", "repository", "license"]
gitCommitMessage = "chore: update citations"
gitUserName = "citation-bot"
gitAmendFromGitHubAction = true

```

--------------------------------

### Install updateCitation using uv

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Install the updateCitation package using uv.

```bash
uv add updateCitation
```

--------------------------------

### Configuration Example for updateCitation

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Example TOML configuration for updateCitation, specifying project details and enabling GitHub and PyPI release tracking.

```toml
[project]
name = "mylib"
version = "1.0.0"
authors = [
    { name = "Jane Doe", email = "jane@example.com" }
]

[project.urls]
Homepage = "https://mylib.org"
Repository = "https://github.com/example/mylib"
License = "https://github.com/example/mylib/blob/main/LICENSE"

[tool.updateCitation]
addGitHubRelease = true
addPyPIrelease = true
projectURLTargets = ["homepage", "repository", "license"]
```

--------------------------------

### Install updateCitation using pipx

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Install the updateCitation package using pipx.

```bash
pipx install updateCitation
```

--------------------------------

### Get Settings Package from pyproject.toml

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pyprojectDOTtoml.md

Instantiates a SettingsPackage by reading configuration from the [tool.updateCitation] and [project] tables in a pyproject.toml file. Use this to load project settings and metadata.

```python
from pathlib import Path
from updateCitation import getSettingsPackage

settings = getSettingsPackage(Path("/my/project/pyproject.toml"))
print(settings.gitCommitMessage)
print(settings.filenameCitationDOTcff)
print(settings.tomlPackageData.get("name"))
```

--------------------------------

### Install updateCitation using pip

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Install the updateCitation package using pip.

```bash
pip install updateCitation
```

--------------------------------

### PyPI Name Canonicalization Examples

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypi.md

Illustrates how package names are canonicalized according to PEP 503, normalizing case, underscores, hyphens, and dots.

```python
# Examples of canonicalization
"My-Package"          # -> "my-package"
"my_package"          # -> "my-package"
"My.Package"          # -> "my-package"
"My___Package"        # -> "my-package"
"My---Package"        # -> "my-package"
"My___---...Package"  # -> "my-package"
```

--------------------------------

### Example Usage of gittyUpGitAmendGitHub

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Demonstrates how to call the gittyUpGitAmendGitHub function with necessary objects and paths. This is typically invoked automatically within a GitHub Actions environment.

```python
# This is typically called from flowControl.here() automatically
# when running in GitHub Actions environment

from updateCitation import (
    CitationNexus, SettingsPackage, gittyUpGitAmendGitHub,
    addGitHubSettings
)
from pathlib import Path

nexus = CitationNexus(repository="https://github.com/example/repo")
settings = SettingsPackage(
    gitUserName="ci-bot",
    gitUserEmail="bot@example.com"
)
settings = addGitHubSettings(settings)

gittyUpGitAmendGitHub(
    settings,
    nexus,
    Path("CITATION.cff"),
    Path("CITATION.cff")
)
```

--------------------------------

### Install updateCitation with uv

Source: https://github.com/hunterhogan/updatecitation/blob/main/README.md

Use this command to add updateCitation as a development dependency in a uv-managed project.

```bash
uv add --dev updateCitation
```

--------------------------------

### Field Protection System Example

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Demonstrates how the field protection system prevents modification of frozen fields after setInStone() is called.

```python
# PyPA source populates version
nexus.version = "1.0.0"
nexus.setInStone("PyPA")

# Later attempt to modify version is silently ignored
nexus.version = "2.0.0"  # No effect; version remains "1.0.0"
```

--------------------------------

### Install developer dependencies with pip

Source: https://github.com/hunterhogan/updatecitation/blob/main/README.md

Install the 'developer' optional dependency group, including updateCitation, into your virtual environment.

```bash
python -m pip install -e ".[developer]"
```

--------------------------------

### Entity Usage Example

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/types.md

Shows how to construct an Entity dictionary for an organization and use it within the CitationNexus. Ensure all required fields for an organization are present.

```python
from updateCitation import CitationNexus

organization = {
    "name": "Department of Physics",
    "address": "123 Science St",
    "city": "Cambridge",
    "country": "UK",
    "website": "https://physics.example.org"
}
```

--------------------------------

### Person Usage Example

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/types.md

Demonstrates how to create a Person dictionary and initialize a CitationNexus object with author data. Ensure correct field names are used.

```python
from updateCitation import CitationNexus

author = {
    "given-names": "Marie",
    "family-names": "Curie",
    "email": "marie@example.com",
    "orcid": "0000-0001-2345-6789"
}

nexus = CitationNexus(authors=[author])
```

--------------------------------

### Handle Optional GitHub Release

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Provides an example of how to handle the optional retrieval of GitHub release data, including error handling for missing data.

```python
from updateCitation import getGitHubRelease
import warnings

with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    release_data = getGitHubRelease(nexus, settings)
    
if release_data:
    # GitHub data available
    nexus.commit = release_data.get("commit")
else:
    # GitHub data unavailable, continue with other sources
    pass
```

--------------------------------

### Run updateCitation using pipx

Source: https://github.com/hunterhogan/updatecitation/blob/main/README.md

Use this command to run updateCitation when installed via pipx, suitable for GitHub Actions or standalone use.

```bash
pipx run updateCitation
```

--------------------------------

### Identifier Usage Example

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/types.md

Illustrates creating a list of Identifier dictionaries with different types and values, then initializing CitationNexus. Ensure the 'type' field uses one of the allowed Literal values.

```python
from updateCitation import CitationNexus, Identifier

identifiers: list[Identifier] = [
    {
        "type": "doi",
        "value": "10.5281/zenodo.1234567",
        "description": "Zenodo software release"
    },
    {
        "type": "url",
        "value": "https://github.com/example/repo/releases/tag/v2.0.0",
        "description": "GitHub release"
    }
]

nexus = CitationNexus(identifiers=identifiers)
```

--------------------------------

### Configure updateCitation for Local Citation File and No PyPI Release

Source: https://github.com/hunterhogan/updatecitation/blob/main/README.md

Use this configuration when your citation file is located in a subdirectory and you do not intend to generate a PyPI release. This example sets the citation file path and disables PyPI release generation.

```toml
[tool.updateCitation]
pathFilenameCitationSSOT = "citations/CITATION.cff"
addPyPIrelease = false
```

--------------------------------

### Selective URL Extraction with PyPA Metadata

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypa.md

This example demonstrates how to limit the extraction of project URLs to a specific subset defined in `projectURLTargets`. Only URLs matching the keys in this set will be added to the CitationNexus object.

```python
# Include only homepage and repository
nexus = addPyPAMetadata(
    nexus,
    tomlPackageData,
    projectURLTargets={"homepage", "repository"}
)
# nexus.licenseDASHurl will not be set even if available in tomlPackageData

```

--------------------------------

### Get PyPI Release URL Dictionary

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypi.md

Constructs a dictionary containing the PyPI release URL for a given CitationNexus object. Requires CitationNexus with title and version.

```python
from updateCitation import CitationNexus, getPyPIrelease

nexus = CitationNexus(
    title="My-Amazing-Package",
    version="1.2.3"
)

pypi_data = getPyPIrelease(nexus)
print(pypi_data)
# Output: {
#     "repositoryDASHartifact": "https://pypi.org/project/my-amazing-package/1.2.3/"
# }
```

--------------------------------

### Handle GithubException during GitHub Authentication

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/errors.md

Shows how GithubException, raised by PyGithub for API failures, is caught internally during GitHub settings configuration. The example demonstrates a fallback mechanism when authentication fails.

```python
from updateCitation import addGitHubSettings, SettingsPackage
from github import GithubException
import os

# If token is invalid, GitHub API will raise GithubException
os.environ["GITHUB_TOKEN"] = "invalid_token"

settings = SettingsPackage()
settings = addGitHubSettings(settings)
# Exception is caught internally; fallback email is used
```

--------------------------------

### Validating Configuration Before Workflow Execution

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/errors.md

Checks critical settings obtained from a configuration file (e.g., 'pyproject.toml') before starting the main workflow. This prevents runtime errors due to missing essential configurations.

```python
from updateCitation import getSettingsPackage
from pathlib import Path

ssettings = getSettingsPackage(Path("pyproject.toml"))

# Verify critical settings
assert settings.tomlPackageData.get("name"), "Package name is required"
assert settings.tomlPackageData.get("version"), "Package version is required"

# Now safe to run the workflow
# ...
```

--------------------------------

### getSettingsPackage()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Load settings from pyproject.toml.

```APIDOC
## Function getSettingsPackage()

### Description
Load settings from pyproject.toml.

### Path
`updateCitation.pyprojectDOTtoml.getSettingsPackage`

### Import
`from updateCitation import getSettingsPackage`

### Signature
```python
def getSettingsPackage(pathFilename: Path) -> SettingsPackage
```

### Documentation
See `api-reference/pyprojectDOTtoml.md`
```

--------------------------------

### Initialize SettingsPackage

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/variables.md

Instantiate the SettingsPackage with custom repository path and citation filenames. This is useful for configuring the citation update process for a specific project structure.

```python
from updateCitation import SettingsPackage
from pathlib import Path

settings = SettingsPackage(
    pathRepository=Path("/my/repo"),
    filenameCitationDOTcff="CITATION.cff",
    addGitHubRelease=True,
    addPyPIrelease=False,
    gitCommitMessage="chore: update citations"
)
```

--------------------------------

### Basic Configuration

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/configuration.md

Use this snippet for the default configuration, relying on all tool settings.

```toml
[tool.updateCitation]
# Use defaults for everything

```

--------------------------------

### Create GitHub Repository Instance

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Use this context manager to create a GitHub repository instance. It requires a CitationNexus object with a repository URL and a SettingsPackage for authentication. The repository details and latest release information are accessible.

```python
from updateCitation import CitationNexus, SettingsPackage, GitHubRepository, addGitHubSettings

nexus = CitationNexus(repository="https://github.com/python/cpython")
settings = SettingsPackage()
settings = addGitHubSettings(settings)

with GitHubRepository(nexus, settings) as repo:
    print(f"Repository: {repo.name}")
    print(f"Stars: {repo.stargazers_count}")
    releases = repo.get_latest_release()
    print(f"Latest release: {releases.tag_name}")
```

--------------------------------

### Run updateCitation from a pip virtual environment

Source: https://github.com/hunterhogan/updatecitation/blob/main/README.md

Execute the updateCitation script directly when it's installed in the active virtual environment.

```bash
updateCitation
```

--------------------------------

### Test Configuration Loading

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/errors.md

Verify that the project's configuration is loaded correctly from the pyproject.toml file. This snippet prints key configuration settings.

```python
from updateCitation import getSettingsPackage
from pathlib import Path

settings = getSettingsPackage(Path("pyproject.toml"))

print(f"Repository: {settings.pathRepository}")
print(f"GitHub token set: {bool(settings.GITHUB_TOKEN)}")
print(f"Citation file: {settings.pathFilenameCitationSSOT}")
print(f"Package data: {settings.tomlPackageData}")
```

--------------------------------

### Initialize CitationNexus with ReferenceDictionary

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/types.md

Demonstrates how to create a CitationNexus instance using a ReferenceDictionary object. Ensure necessary types are imported.

```python
from updateCitation import CitationNexus, ReferenceDictionary

reference: ReferenceDictionary = {
    "title": "Example Paper on Machine Learning",
    "authors": [
        {"given-names": "Jane", "family-names": "Smith"}
    ],
    "journal": "Journal of Machine Learning",
    "year": 2023,
    "volume": 42,
    "issue": 3,
    "pages": "123-145",
    "doi": "10.1234/example",
    "url": "https://example.org/paper"
}

nexus = CitationNexus(
    preferredDASHcitation=reference
)
```

--------------------------------

### getSettingsPackage

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pyprojectDOTtoml.md

Instantiates a SettingsPackage from a pyproject.toml file, extracting settings from the [tool.updateCitation] table and project data.

```APIDOC
## Function: getSettingsPackage

### Description
Instantiate a `SettingsPackage` from a `pyproject.toml` file.

### Signature
```python
def getSettingsPackage(pathFilename: Path) -> SettingsPackage
```

### Parameters
#### Path Parameters
- **pathFilename** (Path) - Yes - Full path to the `pyproject.toml` file.

### Return Value
**Type:** `SettingsPackage`
A configured `SettingsPackage` instance with `tomlPackageData` populated from the `[project]` table.

### Behavior
1. Reads `pyproject.toml` file from `pathFilename`
2. Extracts values from `[tool.updateCitation]` table if present
3. Instantiates `SettingsPackage` with those values
4. Calls `get_pyprojectDOTtoml()` to populate `tomlPackageData` from the `[project]` table
5. Returns the configured `SettingsPackage`

### Example
```python
from pathlib import Path
from updateCitation import getSettingsPackage

settings = getSettingsPackage(Path("/my/project/pyproject.toml"))
print(settings.gitCommitMessage)
print(settings.filenameCitationDOTcff)
print(settings.tomlPackageData.get("name"))
```
```

--------------------------------

### Load Settings Package from pyproject.toml

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Loads repository settings from a pyproject.toml file. Requires a Path object for the filename.

```python
from updateCitation import getSettingsPackage
from pathlib import Path

# Example usage:
settings = getSettingsPackage(Path("pyproject.toml"))
```

--------------------------------

### Inspect Settings Package

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Retrieves and prints details about the settings package, including the citation file path, GitHub token status, and package name.

```python
from updateCitation import getSettingsPackage
from pathlib import Path

settings = getSettingsPackage(Path("pyproject.toml"))
print(f"Citation file: {settings.pathFilenameCitationSSOT}")
print(f"GitHub token set: {bool(settings.GITHUB_TOKEN)}")
print(f"Package name: {settings.tomlPackageData.get('name')}")
```

--------------------------------

### Field Filtering Example

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/citationFileFormat.md

Demonstrates how CitationNexus excludes falsy field values like empty lists, empty strings, and None from the output. Only truthy values are included.

```python
# Empty lists, empty strings, and None values are excluded
nexus = CitationNexus(
    title="MyProject",
    keywords=[],  # Excluded from output
    abstract=None,  # Excluded from output
    authors=[{"given-names": "Jane", "family-names": "Smith"}]  # Included
)
```

--------------------------------

### Basic Usage of updateCitation

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Demonstrates the basic import statement for using the updateCitation library.

```python
import updateCitation
```

--------------------------------

### GitHub Action for CITATION.cff Update

Source: https://github.com/hunterhogan/updatecitation/blob/main/README.md

This GitHub Actions workflow automatically updates the CITATION.cff file on push events. It requires checkout, Python setup, and runs updateCitation using pipx.

```yaml
name: Update CITATION.cff

on:
  push:
  workflow_dispatch:

permissions:
  contents: write

jobs:
  updateCitation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: '3.13'
      - name: Run updateCitation
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: pipx run updateCitation
```

--------------------------------

### Import All Common Items

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Import all frequently used components from the updateCitation package. This is the recommended way to import most items.

```python
from updateCitation import (
    here,
    CitationNexus,
    SettingsPackage,
    getSettingsPackage,
    add_pyprojectDOTtoml,
    addCitation,
    writeCitation,
    addPyPAMetadata,
    compareVersions,
    addGitHubRelease,
    addGitHubSettings,
    addPyPIrelease,
)
```

--------------------------------

### Handle FREAKOUT Exception for Repository Creation

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/errors.md

Demonstrates how to catch the custom FREAKOUT exception when creating a GitHub repository context. This is typically used when essential repository information is missing.

```python
from updateCitation import FREAKOUT, GitHubRepository, CitationNexus, SettingsPackage

nexus = CitationNexus()  # repository is None by default
settings = SettingsPackage()

try:
    with GitHubRepository(nexus, settings) as repo:
        print(repo.name)
except FREAKOUT:
    print("Error: Citation repository URL is required")
```

--------------------------------

### Get GitHub Release Data

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Retrieves the latest release information from a GitHub repository. Use this when you need to fetch details about a specific GitHub release, such as its commit SHA, publication date, and URL. Requires CitationNexus and SettingsPackage objects.

```python
from updateCitation import CitationNexus, SettingsPackage, getGitHubRelease, addGitHubSettings

nexus = CitationNexus(
    repository="https://github.com/example/mylib",
    version="2.0.0",
    title="mylib"
)
settings = SettingsPackage()
settings = addGitHubSettings(settings)

release_data = getGitHubRelease(nexus, settings)
if release_data:
    print(f"Release date: {release_data['dateDASHreleased']}")
    print(f"Commit: {release_data['commit']}")
    print(f"URL: {release_data['repositoryDASHcode']}")
    print(f"Identifiers: {release_data['identifiers']}")
else:
    print("Failed to retrieve release data")
```

--------------------------------

### addGitHubSettings()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Configures GitHub authentication and git user email on a SettingsPackage. It resolves the GitHub token from environment variables and fetches the user's noreply email.

```APIDOC
## Function: addGitHubSettings()

Configure GitHub authentication and git user email on a `SettingsPackage`.

### Signature

```python
def addGitHubSettings(truth: SettingsPackage) -> SettingsPackage
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| truth | SettingsPackage | Yes | Settings object to configure. |

### Return Value

**Type:** `SettingsPackage`

The `truth` object with `GITHUB_TOKEN` and `gitUserEmail` populated.

### Behavior

1. Populates `truth.GITHUB_TOKEN` from:
   - Existing value in `truth.GITHUB_TOKEN` (if already set)
   - `GITHUB_TOKEN` environment variable
   - `GH_TOKEN` environment variable (fallback)
2. Resolves `truth.gitUserEmail`:
   - Queries GitHub API for authenticated user's noreply email (`{id}+{login}@users.noreply.github.com`)
   - Falls back to `GITHUB_ACTOR` environment variable with noreply format
   - Falls back to `gitUserEmailFALLBACK` constant (`action@github.com`)

### Example

```python
from updateCitation import SettingsPackage, addGitHubSettings
import os

# Set token via environment variable
os.environ["GITHUB_TOKEN"] = "ghp_xxxxxxxxxxxx"

settings = SettingsPackage()
settings = addGitHubSettings(settings)

print(f"Token: {settings.GITHUB_TOKEN}")
print(f"Email: {settings.gitUserEmail}")
```

### Notes

- Token is obtained from environment variables if not already set in `SettingsPackage`
- If GitHub API query fails, silently falls back to environment-based resolution
- This function is idempotent: calling it multiple times with the same input produces the same result
```

--------------------------------

### GitHubRepository()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Creates a GitHub repository instance as a context manager. It extracts repository details from a CitationNexus object and uses a SettingsPackage for authentication.

```APIDOC
## Function: GitHubRepository()

Create a GitHub repository instance as a context manager.

### Signature

```python
@contextmanager
def GitHubRepository(
    nexusCitation: CitationNexus,
    truth: SettingsPackage
) -> Generator[Repository]
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| nexusCitation | CitationNexus | Yes | Citation object containing the `repository` URL. |
| truth | SettingsPackage | Yes | Settings object containing GitHub authentication token. |

### Yields

| Type | Description |
|------|-------------|
| github.Repository.Repository | A GitHub repository instance. |

### Raises

| Error Type | Condition |
|------------|-----------|
| FREAKOUT | If `nexusCitation.repository` is falsy. |

### Behavior

1. Validates that `nexusCitation.repository` is set (non-empty)
2. Extracts owner and repository name from the URL:
   - Removes `https://github.com/` prefix
   - Removes `.git` suffix if present
3. Obtains authenticated GitHub API client via `GitHubClient()`
4. Retrieves repository instance using `client.get_repo()`
5. Yields the repository and ensures client is properly closed

### Example

```python
from updateCitation import CitationNexus, SettingsPackage, GitHubRepository, addGitHubSettings

nexus = CitationNexus(repository="https://github.com/python/cpython")
settings = SettingsPackage()
settings = addGitHubSettings(settings)

with GitHubRepository(nexus, settings) as repo:
    print(f"Repository: {repo.name}")
    print(f"Stars: {repo.stargazers_count}")
    releases = repo.get_latest_release()
    print(f"Latest release: {releases.tag_name}")
```
```

--------------------------------

### Handle Different License Formats

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypa.md

Demonstrates how the getPyPAMetadata function handles both string-based (PEP 621) and dictionary-based (PEP 639) license specifications, producing a consistent license expression.

```python
# PEP 621 format (string)
packageData1 = {"name": "pkg", "license": "MIT"}

# PEP 639 format (dictionary with text key)
packageData2 = {"name": "pkg", "license": {"text": "MIT"}}

# Both produce the same metadata.license_expression = "MIT"
```

--------------------------------

### Initialize and Freeze CitationNexus with pyproject.toml

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/variables.md

Demonstrates initializing a CitationNexus object and then freezing fields managed by 'pyproject.toml' using the setInStone method. This prevents subsequent modifications to these specific fields.

```python
nexusCitation = CitationNexus()
# ... populate fields from pyproject.toml ...
nexusCitation.setInStone("pyprojectDOTtoml")
# Now authors, contact, and title cannot be modified
```

--------------------------------

### Importing UpdateCitation Types

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/types.md

Demonstrates the primary import path for all types from the updateCitation module.

```python
from updateCitation import (
    Person,
    Entity,
    Identifier,
    ReferenceDictionary,
    GitHubReleaseData,
    CitationNexus,
    SettingsPackage,
    FREAKOUT
)
```

--------------------------------

### SettingsPackage

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/variables.md

Stores repository path, git configuration, and feature flags for the citation update workflow.

```APIDOC
## Class: SettingsPackage

Store repository path, git configuration, and feature flag for the workflow.

### Signature
```python
@attrs.define(slots=False)
class SettingsPackage:
    """Store repository path, git configuration, and feature flag for the workflow."""
```
```

--------------------------------

### Load Existing CITATION.cff into CitationNexus

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Loads citation metadata from an existing CITATION.cff file into a CitationNexus object. Requires the path to the CITATION.cff file.

```python
from updateCitation import addCitation, CitationNexus
from pathlib import Path

# Example usage:
# Assuming nexus_citation is an existing CitationNexus object
# nexus_citation = addCitation(nexus_citation, Path("CITATION.cff"))
```

--------------------------------

### Import SettingsPackage Class

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Import the SettingsPackage class from the updateCitation package.

```python
from updateCitation import SettingsPackage
```

--------------------------------

### compareVersions()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Compare two version strings.

```APIDOC
## Function compareVersions()

### Description
Compare two version strings.

### Path
`updateCitation.pypa.compareVersions`

### Import
`from updateCitation import compareVersions`

### Signature
```python
def compareVersions(comparand: str, comparator: str) -> int
```

### Documentation
See `api-reference/pypa.md`
```

--------------------------------

### Read Project Table from pyproject.toml

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pyprojectDOTtoml.md

Populates the tomlPackageData field of a SettingsPackage with the contents of the [project] table from a pyproject.toml file. Ensure the pathFilenamePackageSSOT is set in the SettingsPackage before calling.

```python
from updateCitation import SettingsPackage, get_pyprojectDOTtoml
from pathlib import Path

settings = SettingsPackage(pathFilenamePackageSSOT=Path("pyproject.toml"))
settings = get_pyprojectDOTtoml(settings)
# settings.tomlPackageData now contains the [project] table
```

--------------------------------

### Write Citation File

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/citationFileFormat.md

Creates a CitationNexus object with project metadata and writes it to a CITATION.cff file. Parent directories are created automatically. The function returns a success status.

```python
from pathlib import Path
from updateCitation import CitationNexus, writeCitation

nexus = CitationNexus(
    title="MyProject",
    cffDASHversion="1.2.0",
    version="1.0.0",
    authors=[{"given-names": "John", "family-names": "Doe"}],
    message="Cite this software with the metadata in this file."
)

success = writeCitation(
    nexus,
    Path("CITATION.cff"),
    Path("docs/CITATION.cff")
)

if success:
    print("CITATION.cff successfully written and validated")
else:
    print("Validation failed")
```

--------------------------------

### Run Complete Citation Update Workflow

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Initiates the full citation update process. Optionally specify a pyproject.toml file path.

```python
from updateCitation import here

# Example usage:
here(pathFilename_pyprojectDOTtoml="/path/to/your/pyproject.toml")
```

--------------------------------

### License Field Format in pyproject.toml

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/configuration.md

Illustrates the PEP 621 format for specifying the software license using a simple string in the [project] section of pyproject.toml.

```toml
# PEP 621 format (string)
license = "MIT"

```

--------------------------------

### Run updateCitation from Current Directory

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/INDEX.md

Executes updateCitation by reading configuration from the local pyproject.toml file.

```python
import updateCitation

updateCitation.here()
```

--------------------------------

### GitHub API Client Context Manager

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Use this context manager to establish a connection to the GitHub API. It requires a GitHub token for authentication.

```python
from updateCitation import GitHubClient

with GitHubClient(token="YOUR_GITHUB_TOKEN") as github:
    # Use the github API client here
    pass
```

--------------------------------

### here()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Run the complete citation update workflow.

```APIDOC
## Function here()

### Description
Run the complete citation update workflow.

### Path
`updateCitation.flowControl.here`

### Import
`from updateCitation import here`

### Signature
```python
def here(pathFilename_pyprojectDOTtoml: str | PathLike[Any] | None = None) -> None
```

### Documentation
See `api-reference/flowControl.md`
```

--------------------------------

### Run updateCitation using uvx

Source: https://github.com/hunterhogan/updatecitation/blob/main/README.md

Execute updateCitation using uvx, an alternative to pipx for managing Python tools.

```bash
uvx updateCitation
```

--------------------------------

### addGitHubSettings()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Configures GitHub authentication settings within the SettingsPackage. This function is essential for enabling GitHub-related operations within the library.

```APIDOC
## addGitHubSettings()

### Description
Configure GitHub authentication on SettingsPackage.

### Signature
```python
def addGitHubSettings(truth: SettingsPackage) -> SettingsPackage
```

### Import
`from updateCitation import addGitHubSettings`
```

--------------------------------

### GitHub Repository Context Manager

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Provides a context manager for interacting with a GitHub repository. It requires CitationNexus and SettingsPackage for initialization.

```python
from updateCitation import GitHubRepository, CitationNexus, SettingsPackage

with GitHubRepository(nexusCitation=citation_nexus, truth=settings) as repo:
    # Interact with the GitHub repository
    pass
```

--------------------------------

### Complete Workflow: Add PyPI Release to Citation

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypi.md

Demonstrates the full process of creating a CitationNexus object and adding PyPI release information to it.

```python
from updateCitation import CitationNexus, addPyPIrelease

# Create and populate citation
nexus = CitationNexus(
    title="mylib",
    version="3.0.0",
    authors=[{"given-names": "John", "family-names": "Doe"}],
    message="Cite this software with the metadata in this file.",
    cffDASHversion="1.2.0"
)

# Add PyPI release information
nexus = addPyPIrelease(nexus)

# Now nexusCitation.repositoryDASHartifact is set
print(nexus.repositoryDASHartifact)
# Output: https://pypi.org/project/mylib/3.0.0/
```

--------------------------------

### Create Authenticated GitHub API Client

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Use this context manager to create an authenticated GitHub API client. Provide a token for authentication or None for unauthenticated access. The client is automatically closed upon exiting the context.

```python
from updateCitation import GitHubClient

# Authenticated access
with GitHubClient("ghp_xxxxxxxxxxxx") as client:
    user = client.get_user()
    print(user.login)

# Unauthenticated access
with GitHubClient(None) as client:
    repo = client.get_repo("python/cpython")
    print(repo.stargazers_count)
```

--------------------------------

### getPyPIrelease()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypi.md

Constructs a dictionary containing the PyPI release URL based on CitationNexus metadata. It normalizes package names and versions to create a valid URL.

```APIDOC
## Function: getPyPIrelease()

Construct the PyPI release URL dictionary from `CitationNexus` metadata.

### Signature

```python
def getPyPIrelease(nexusCitation: CitationNexus) -> dict[str, Any]
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| nexusCitation | CitationNexus | Yes | Citation object containing `title` and `version`. |

### Return Value

**Type:** `dict[str, Any]`

Dictionary with key `"repositoryDASHartifact"` mapped to the PyPI release URL string.

### Return Value Structure

```python
{
    "repositoryDASHartifact": "https://pypi.org/project/{canonical_package_name}/{version}/"
}
```

### Raises

| Error Type | Condition |
|------------|-----------|
| ValueError | If `nexusCitation.title` is falsy. |
| ValueError | If `nexusCitation.version` is falsy. |

### Behavior

1. Validates that `nexusCitation.title` is set (non-empty)
2. Validates that `nexusCitation.version` is set (non-empty)
3. Canonicalizes the package name using `packaging.utils.canonicalize_name()`
4. Constructs the PyPI URL: `https://pypi.org/project/{canonical_name}/{version}/`
5. Returns dictionary with this URL

### Example

```python
from updateCitation import CitationNexus, getPyPIrelease

nexus = CitationNexus(
    title="My-Amazing-Package",
    version="1.2.3"
)

pypi_data = getPyPIrelease(nexus)
print(pypi_data)
# Output: {
#     "repositoryDASHartifact": "https://pypi.org/project/my-amazing-package/1.2.3/"
# }
```

### Name Canonicalization

Package names are canonicalized according to PEP 503:
- Converted to lowercase
- Underscores, hyphens, and dots are normalized to hyphens
- Runs of underscores/hyphens/dots are collapsed to a single hyphen

```python
# Examples of canonicalization
"My-Package"          # -> "my-package"
"my_package"          # -> "my-package"
"My.Package"          # -> "my-package"
"My___Package"        # -> "my-package"
"My---Package"        # -> "my-package"
"My___---...Package"  # -> "my-package"
```

### URL Format

The URL points to the specific version release page on PyPI:

```
https://pypi.org/project/{package_name}/{version}/
```

Examples:
- `https://pypi.org/project/numpy/1.24.0/`
- `https://pypi.org/project/django/4.2.1/`
- `https://pypi.org/project/pandas/2.0.0/`

### Notes

- The function does not verify that the package exists on PyPI
- Version strings are used as-is (no validation or normalization)
- URL includes trailing slash per PyPI standard
```

--------------------------------

### get_pyprojectDOTtoml

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pyprojectDOTtoml.md

Reads the [project] table from pyproject.toml into a SettingsPackage object.

```APIDOC
## Function: get_pyprojectDOTtoml

### Description
Read the `[project]` table from `pyproject.toml` into `SettingsPackage`.

### Signature
```python
def get_pyprojectDOTtoml(truth: SettingsPackage) -> SettingsPackage
```

### Parameters
#### Path Parameters
- **truth** (SettingsPackage) - Yes - Settings object with `pathFilenamePackageSSOT` set.

### Return Value
**Type:** `SettingsPackage`
The `truth` object with `tomlPackageData` populated from `[project]` table.

### Behavior
Parses the `[project]` table from the TOML file specified in `truth.pathFilenamePackageSSOT` and stores the dictionary in `truth.tomlPackageData`.

### Example
```python
from updateCitation import SettingsPackage, get_pyprojectDOTtoml
from pathlib import Path

settings = SettingsPackage(pathFilenamePackageSSOT=Path("pyproject.toml"))
settings = get_pyprojectDOTtoml(settings)
# settings.tomlPackageData now contains the [project] table
```
```

--------------------------------

### GitHubClient()

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Creates an authenticated or unauthenticated GitHub API client as a context manager. It handles token-based authentication and ensures proper resource cleanup.

```APIDOC
## Function: GitHubClient()

Creates an authenticated GitHub API client as a context manager.

### Signature

```python
@contextmanager
def GitHubClient(tokenAsStr: str | None) -> Generator[github.Github]
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tokenAsStr | str \| None | Yes | GitHub authentication token string, or `None` for unauthenticated access. |

### Yields

| Type | Description |
|------|-------------|
| github.Github | An authenticated (or unauthenticated) GitHub API client. |

### Behavior

- If `tokenAsStr` is provided, authenticates with `github.Auth.Token()`
- If `tokenAsStr` is `None`, connects without authentication (public access only)
- Automatically closes the client when the context manager exits
- Ensures proper resource cleanup even if an exception occurs

### Example

```python
from updateCitation import GitHubClient

# Authenticated access
with GitHubClient("ghp_xxxxxxxxxxxx") as client:
    user = client.get_user()
    print(user.login)

# Unauthenticated access
with GitHubClient(None) as client:
    repo = client.get_repo("python/cpython")
    print(repo.stargazers_count)
```

### Notes

- Tokens can be created at https://github.com/settings/tokens
- Unauthenticated requests are limited to 60 per hour per IP
- Authenticated requests can be up to 5000 per hour depending on token permissions
```

--------------------------------

### Fetch and Print GitHub Release Data

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/types.md

Shows how to use `getGitHubRelease` to fetch release data and access its fields. Handles cases where 'commit' might be absent.

```python
from updateCitation import getGitHubRelease, SettingsPackage, CitationNexus

nexus = CitationNexus(
    repository="https://github.com/example/lib",
    version="1.0.0",
    title="lib"
)
settings = SettingsPackage()

release_data = getGitHubRelease(nexus, settings)
if release_data:
    print(f"Released: {release_data['dateDASHreleased']}")
    print(f"Commit: {release_data.get('commit')}")
    print(f"URL: {release_data['repositoryDASHcode']}")
```

--------------------------------

### Configure GitHub Settings and Git User Email

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/github.md

Configure GitHub authentication token and git user email within a SettingsPackage. The token is sourced from environment variables if not already present. The git user email is resolved via GitHub API or environment variables.

```python
from updateCitation import SettingsPackage, addGitHubSettings
import os

# Set token via environment variable
os.environ["GITHUB_TOKEN"] = "ghp_xxxxxxxxxxxx"

settings = SettingsPackage()
settings = addGitHubSettings(settings)

print(f"Token: {settings.GITHUB_TOKEN}")
print(f"Email: {settings.gitUserEmail}")
```

--------------------------------

### Metadata Flow Diagram

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/README.md

Illustrates the sequence of metadata population and output generation within the updateCitation package.

```flow
pyproject.toml → CitationNexus
CITATION.cff   → CitationNexus (merge)
PyPA metadata  → CitationNexus (merge)
GitHub release → CitationNexus (merge)
PyPI package   → CitationNexus (merge)
                 ↓
           writeCitation()
                 ↓
           CITATION.cff (validated)
                 ↓
         GitHub Actions push (optional)
```

--------------------------------

### Minimal Project URLs Configuration

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/configuration.md

Limit the project URLs included in the citation to only the repository URL by setting `projectURLTargets`.

```toml
[tool.updateCitation]
projectURLTargets = ["repository"]  # Only include repository URL

[project.urls]
Repository = "https://github.com/example/project"
Homepage = "https://example.com"  # Not included

```

--------------------------------

### Normalize Project URLs

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypa.md

Illustrates how project URLs provided in a package dictionary are normalized to lowercase keys when processed by getPyPAMetadata. This ensures consistent access to URL information.

```python
packageData = {
    "name": "pkg",
    "urls": {
        "Homepage": "https://example.com",
        "Repository": "https://github.com/example/pkg"
    }
}

metadata = getPyPAMetadata(packageData)
# metadata.project_urls =
#     {"homepage": "https://example.com",
#      "repository": "https://github.com/example/pkg"}
```

--------------------------------

### Populate CitationNexus with PyPA Metadata

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/api-reference/pypa.md

Use this snippet to add version, keywords, license, and project URLs from `pyproject.toml` data to a CitationNexus object. It requires the `CitationNexus` class and the `addPyPAMetadata` function. The `projectURLTargets` set controls which URLs are extracted.

```python
from updateCitation import CitationNexus, addPyPAMetadata

tomlPackageData = {
    "name": "mylib",
    "version": "2.3.4",
    "keywords": ["machine-learning", "science"],
    "license": "Apache-2.0",
    "urls": {
        "Homepage": "https://mylib.example.com",
        "Repository": "https://github.com/example/mylib",
        "License": "https://github.com/example/mylib/blob/main/LICENSE"
    }
}

nexus = CitationNexus()
nexus = addPyPAMetadata(
    nexus,
    tomlPackageData,
    projectURLTargets={"homepage", "repository", "license"}
)

print(f"Version: {nexus.version}")  # "2.3.4"
print(f"Keywords: {nexus.keywords}")  # ["machine-learning", "science"]
print(f"License: {nexus.license}")  # "Apache-2.0"
print(f"Homepage: {nexus.url}")  # "https://mylib.example.com"
print(f"Repository: {nexus.repository}")  # "https://github.com/example/mylib"
print(f"License URL: {nexus.licenseDASHurl}")  # "https://github.com/example/mylib/blob/main/LICENSE"

```

--------------------------------

### Populate CitationNexus from pyproject.toml

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/EXPORTED_API.md

Adds citation data from a pyproject.toml file to an existing CitationNexus object. Requires a SettingsPackage for truth.

```python
from updateCitation import add_pyprojectDOTtoml, CitationNexus, SettingsPackage

# Example usage:
# Assuming nexus_citation is an existing CitationNexus object
# and settings is a loaded SettingsPackage object
# nexus_citation = add_pyprojectDOTtoml(nexus_citation, settings)
```

--------------------------------

### Setting Required Fields Before Freezing

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/errors.md

Ensures all required fields for a specific source (e.g., 'pyprojectDOTtoml') are set before calling `setInStone()`. This is a best practice to avoid validation errors.

```python
from updateCitation import CitationNexus

nexus = CitationNexus()

# Set all required fields for pyprojectDOTtoml source
nexus.title = "MyLib"
nexus.authors = [{"given-names": "Jane", "family-names": "Doe"}]
nexus.contact = []

# Now safe to freeze
nexus.setInStone("pyprojectDOTtoml")
```

--------------------------------

### Catching ValueError for Missing Data

Source: https://github.com/hunterhogan/updatecitation/blob/main/_autodocs/errors.md

Demonstrates how to catch `ValueError` exceptions that occur when required data is missing for operations like adding PyPI release information. This allows for graceful error reporting.

```python
from updateCitation import CitationNexus, addPyPIrelease

nexus = CitationNexus()
# Missing title and version

try:
    nexus = addPyPIrelease(nexus)
except ValueError as e:
    print(f"Cannot add PyPI data: {e}")
    # Output: "Package name (title) is required to get PyPI release info."
```