----------------------------------------------------------------------
This is the API documentation for the goodreads_normalizer library.
----------------------------------------------------------------------


## Classes

Main classes provided by the package


Author(*, name: str = '', pen_name: str | None = None) -> None

This object stores the information about an author.
The Author may have a nom de plume.

Attributes:
    name (str):
    pen_name (str): Author's Nom de plume

Examples:
    ```{python}
    from goodreads_normalizer import Author

    author = Author(name="Brandon Sanderson")
    print(f"Author: {author.display_name}")
    print(f"Slug: {author.slug}")

    author = Author(name="Shirtaloon")
    print(f"Display Name: {author.display_name}")
    print(f"Is Pen Name: {author.is_pen_name}")
    print(f"Slug: {author.slug}")
    print(f"Pen Name: {author.pen_name}")
    print(f"Name: {author.name}")
    ```

If the Author name is in the NARRATORS list and is also *not* in the AUTHORS list,
a ValueError will be raised, which is then transformed into a ValidationError by pydantic.

Book(*, book_id: str, title_data: goodreads_normalizer.models.book_title.BookTitleData, authors: list[goodreads_normalizer.models.author.Author] = <factory>, narrators: list[goodreads_normalizer.models.narrator.Narrator] = <factory>, isbn: str | None, isbn13: str | None, rating: int, publisher: str, binding: str, pages: int, year_published: str, original_publication_year: str, date_read: datetime.date | None = None, date_added: datetime.date | None = None, book_shelves: list[str] = [], book_shelves_with_positions: list[str] = [], exclusive_shelf: str, my_review: str, spoiler: str, private_notes: str, read_count: int, owned_copies: int) -> None

This model stores all row data read from goodreads_export.csv file.
As part of the book model creation. Validation and normalization is performed.

BookTitleData:

    original_title (str):

    title (str): Book title only

    series (list[Series]): Series data for current Book.

Attributes:
    book_id (str):
    title_data (BookTitleData):
    authors (list[Author]):
    narrators (list[Narrator]):
    isbn (str|None):
    isbn13 (str|None):
    rating (int):
    publisher (str):
    binding (str):
    pages (int):
    year_published (str):
    original_publication_year (str):
    date_read (datetime.date):
    date_added (datetime.date):
    book_shelves (list[str]):
    book_shelves_with_positions (list[str]):
    exclusive_shelf (str):
    my_review (str):
    spoiler (str):
    private_notes (str):
    read_count (int):
    owned_copies (int):

Narrator(*, name: str) -> None

The Narrator model stores information about a narrator found in the "Additional Authors" column

Attributes:
    name: The full name of the narrator.

Examples:
    ```{python}
    from goodreads_normalizer import Narrator

    narrator = Narrator(name="Travis Baldree")
    print(f"Narrator Name: {narrator.full_name}")
    print(f"Narrator Name (N): {narrator.name_with_short_tag}")
    print(f"Narrator Name (Narrator): {narrator.name_with_long_tag}")
    ```


## Author Methods

Methods for the Author class


Author.display_name

Provides either the Author's full real name, or their nom de plume

Returns:
    str: Author's nom de plume or their true full name if known

Author.first_name

Gives access to the Author's first name if available, else ""

Author.last_name

Gives access to the Author's last name if available, else their nom deplume

Author.last_first_name

Generates the Author's name as "Last Name, First Name"

Author.is_pen_name

Author.real_name

Author.slug

Generates a slug string format: 'last-first' using active name.
Active name will either be the Author's nom de plume or their real name

Returns:
    str: The string will be formatted suitable for the web


## Book Methods

Methods for the Book class


Book.title

Gives the title of the book, excluding series name and position

Book.original_title

Gives the original book title with additional spaces removed.

Book.series

Gives access to the Series Model

Book.is_a_crossover

This is True if the book belongs to more than a single series.
Example: "Cleaning the Gold" Belongs to both "Will Trent" and "Jack Reacher"

Book.is_series_collection

This is True if the book is a collection containing more than one book from a single series

Note: Does not work for collection with multiple authors

Book.is_single_book

This is True if the book is part of a single series and is not a collection.

Book.is_a_stand_alone_book

This is a standalone book. Does not belong to any series


## Narrator Methods

Methods for the Narrator class


Narrator.full_name

Gives access to Narrator's Full Name

Narrator.first_name

Gives access to the Narrator's first name if available, else ""

Narrator.last_name

Gives access to the Narrator's last name if available, else their nom deplume

Narrator.slug

Gives an http safe slug based on the narrator's full name. lastname-firstname

Narrator.name_with_short_tag

Gives narrator's full name with short tag
Example:
    "Travis Baldree (N)"

Narrator.name_with_long_tag

Gives narrator's full name with long tag
Example:
    "Travis Baldree (Narrator)"


## I/O Utilities


load_csv(file_path: pathlib.Path) -> list[goodreads_normalizer.models.book.Book]

Loads and parses a Goodreads CSV file return a list of Books

Args:
    file_path: GoodReads source csv file

Returns:
    list[Book]:

Raises:
    GoodreadsImportError: If there is an issue reading the csv source data

export_to_stream(books: list[goodreads_normalizer.models.book.Book], stream: typer.models.FileTextWrite, name_format: goodreads_normalizer.io.csv.NameFormatter) -> None

Writes the book data directly into an open file-like stream (file or stdout).

Format is managed by [NameFormatter](`NameFormatter`).

Args:
    books: List of books to export.
    stream: An open, writable file-like object (e.g. a file handle
        opened in text mode, or ``sys.stdout``) that the formatted
        book data is written to. The stream is not closed by this
        function.
    name_format: NameFormatter controlling how author and narrator names
        are rendered in the output.

Returns:
    Data is written to `stream` as a side effect.

NameFormatter(*values)

This Enum helps control the formatting of Narrator names.


----------------------------------------------------------------------
This is the CLI documentation for the package.
----------------------------------------------------------------------

## CLI: normalize-goodreads

```

```