yubetsu-cite 1.0.0

Yubetsu Cite is a Python tool that simplifies the generation of academic citations in various formats.

Yubetsu Cite Documentation

Overview

Yubetsu Cite is a Python implementation that helps in generating formatted citations for academic publications in different styles, including APA, MLA, AMA, Chicago, NLM, and IEEE. The Publication class encapsulates all the necessary information related to a publication and provides methods to format the citation based on specified styles.

Classes

CitationError

class CitationError(ValueError):
    """Custom exception for citation generation errors."""

• Description: Custom exception raised when there are issues related to citation generation, such as missing mandatory fields.

UnsupportedFormatError

class UnsupportedFormatError(ValueError):
    """Exception raised for unsupported citation formats."""

• Description: Custom exception raised when an unsupported citation format is requested.

Publication

class Publication:

Attributes

• authors (List[str]): A list of author names.
• year (Optional[int]): Year of publication (required).
• month (Optional[int]): Month of publication (1-12).
• title (str): Title of the article or work (required).
• journal (str): Journal or container name (required).
• volume (Optional[int]): Volume of the journal.
• issue (Optional[int]): Issue number of the journal.
• pages (Optional[str]): Page range (e.g., '23-45').
• doi (Optional[str]): DOI of the article or permalink.
• database (Optional[str]): Database name (e.g., Project MUSE).
• access_date (Optional[str]): Date of access (for online sources).
• citekey (Optional[str]): Unique key for citation generation.

Initialization

def __init__(self, authors: List[str], year: Optional[int], month: Optional[int], title: str, journal: str, volume: Optional[int] = None, issue: Optional[int] = None, pages: Optional[str] = None, doi: Optional[str] = None, database: Optional[str] = None, access_date: Optional[str] = None, citekey: Optional[str] = None):

• Parameters:
  • authors: List of author names (required).
  • year: Year of publication (required).
  • month: Month of publication (optional).
  • title: Title of the article or work (required).
  • journal: Journal or container name (required).
  • volume: Volume of the journal (optional).
  • issue: Issue number of the journal (optional).
  • pages: Page range (optional).
  • doi: DOI of the article or permalink (optional).
  • database: Database name (optional).
  • access_date: Date of access (optional).
  • citekey: Unique citation key (optional). If not provided, it defaults to the author's last name followed by the publication year.
• Raises:
  • CitationError: If any of the mandatory fields (authors, title, journal, year) are missing.

Methods

1. format_author_apa

   def format_author_apa(self, author: str) -> str:
   

   • Description: Formats a single author's name into APA style (Last, F. M.).
   • Parameters:
     • author: The name of the author.
   • Returns: Formatted author name in APA style.
   • Raises: CitationError if the author's format is invalid.

2. format_authors_apa

   def format_authors_apa(self) -> str:
   

   • Description: Formats the list of authors according to APA style.
   • Returns: A string of formatted authors in APA style.

3. format_author_mla

   def format_author_mla(self, author: str, index: int, total_authors: int) -> str:
   

   • Description: Formats a single author's name into MLA style.
   • Parameters:
     • author: The name of the author.
     • index: The index of the author in the list.
     • total_authors: Total number of authors.
   • Returns: Formatted author name in MLA style.

4. format_authors_mla

   def format_authors_mla(self) -> str:
   

   • Description: Formats the list of authors according to MLA style.
   • Returns: A string of formatted authors in MLA style.

5. format_author_ama

   def format_author_ama(self, author: str) -> str:
   

   • Description: Formats a single author's name into AMA style (Last FirstInitial MiddleInitial).
   • Parameters:
     • author: The name of the author.
   • Returns: Formatted author name in AMA style.

6. format_authors_ama

   def format_authors_ama(self) -> str:
   

   • Description: Formats the list of authors according to AMA style rules.
   • Returns: A string of formatted authors in AMA style.

7. format_author_nlm

   def format_author_nlm(self, author: str) -> str:
   

   • Description: Formats a single author's name into NLM style.
   • Parameters:
     • author: The name of the author.
   • Returns: Formatted author name in NLM style.

8. format_authors_nlm

   def format_authors_nlm(self) -> str:
   

   • Description: Formats the list of authors according to NLM style rules.
   • Returns: A string of formatted authors in NLM style.

9. format_authors_chicago

   def format_authors_chicago(self) -> str:
   

   • Description: Formats the list of authors according to Chicago style rules.
   • Returns: A string of formatted authors in Chicago style.

10. format_authors_ieee

    def format_authors_ieee(self, in_text: bool = False) -> str:
    

    • Description: Formats the list of authors according to IEEE style rules.
    • Parameters:
      • in_text: Boolean flag to indicate if the citation is in-text (default is False).
    • Returns: A string of formatted authors in IEEE style.

11. generate_citation

    def generate_citation(self, format_type: str = "APA", style: str = "raw") -> str:
    

    • Description: Generates a citation in the specified format and style.
    • Parameters:
      • format_type: The citation format ('APA', 'MLA', 'AMA', 'NLM', 'CHICAGO', 'IEEE', 'BIBTEX').
      • style: The style in which the citation should be formatted ('raw' or 'html').
    • Returns: Formatted citation string.
    • Raises:
      • UnsupportedFormatError: If an unsupported format or style is specified.

12. generate_apa_citation

    def generate_apa_citation(self, style: str) -> str:
    

    • Description: Generates a citation in APA style.
    • Parameters:
      • style: The desired output style ('raw' or 'html').
    • Returns: Formatted APA citation string.

13. generate_mla_citation

    def generate_mla_citation(self, style: str) -> str:
    

    • Description: Generates a citation in MLA style.
    • Parameters:
      • style: The desired output style ('raw' or 'html').
    • Returns: Formatted MLA citation string.

14. generate_ama_citation

    def generate_ama_citation(self, style: str) -> str:
    

    • Description: Generates a citation in AMA style.
    • Parameters:
      • style: The desired output style ('raw' or 'html').
    • Returns: Formatted AMA citation string.

15. generate_raw_nlm_citation

    def generate_raw_nlm_citation(self) -> str:
    

    • Description: Generates a raw text NLM citation for a journal article.
    • Returns: Formatted raw NLM citation string.

16. generate_html_nlm_citation

    def generate_html_nlm_citation(self) -> str:
    

    • Description: Generates an HTML formatted NLM citation for a journal article.
    • Returns: Formatted HTML NLM citation string.

17. generate_raw_chicago_citation

    def generate_raw_chicago_citation(self) -> str:
    

    • Description: Generates a raw text Chicago-style citation for a journal article.
    • Returns: Formatted raw Chicago-style citation string.

18. generate_html_chicago_citation

    def generate_html_chicago_citation(self) -> str:
    

    • Description: Generates an HTML formatted Chicago-style citation for a journal article.
    • Returns: Formatted HTML Chicago-style citation string.

19. generate_ieee_citation

    def generate_ieee_citation(self, in_text: bool = False) -> str:
    

    • Description: Generates a citation in IEEE style.
    • Parameters:
      • in_text: Boolean flag to indicate if the citation is in-text (default is False).
    • Returns: Formatted IEEE citation string.

20. generate_bibtex_citation

    def generate_bibtex_citation(self) -> str:
    

    • Description: Generates a BibTeX citation for the publication.
    • Returns: Formatted BibTeX citation string.

21. generate

Example Usage

# Creating a Publication instance
publication = Publication(
    authors=["John Doe", "Jane Smith", "Alice Johnson"],
    year=2024,
    month=9,
    title="A Comprehensive Study on Something Interesting",
    journal="Journal of Interesting Studies",
    volume=34,
    issue=2,
    pages="123-145",
    doi="10.1000/j.jis.2024.09.001"
)

# Generating an APA citation
apa_citation = publication.generate_citation(format_type="APA")
print(apa_citation)

# Generating a MLA citation
mla_citation = publication.generate_citation(format_type="MLA")
print(mla_citation)

Error Handling

The code includes custom exceptions to handle errors related to citation generation:

• CitationError: Raised when required fields are missing or incorrectly formatted.
• UnsupportedFormatError: Raised when an unsupported citation format is requested.

Dependencies

This code does not require any external libraries and runs in any standard Python environment (Python 3.6+).

Testing

The class is designed for straightforward unit testing. You can create instances of the Publication class and verify the output of citation formats by checking the generated strings against known good values.

📚 Resources

Here you can find useful links and attributions related to our project. Make sure to review the license and citation styles below.

🏢 Company Website

Learn more about our company and other projects we’re working on:

• Company Website: https://www.yubetsu.com

⚖️ License and Attribution

This project is licensed under the Apache License 2.0. Please make sure to review the full license before using or modifying the project:

• License Information: https://www.apache.org/licenses/

📝 Citation Style Attributions

Yubetsu Cite supports several citation styles. Below are the references and attributions for these standards:

• APA Style: APA Style Guide, 7th Edition
• MLA Style: MLA Handbook, 9th Edition
• AMA Style: AMA Manual of Style, 11th Edition
• IEEE Style: IEEE Citation Guidelines
• Chicago Style: Chicago Manual of Style, 17th Edition
• NLM Style: National Library of Medicine Style Guide

📖 Further Reading

For additional resources on citation formats and academic writing, explore the links below:

• APA Style: https://apastyle.apa.org
• MLA Style: https://style.mla.org
• AMA Style: https://www.amamanualofstyle.com
• IEEE Citation Reference: https://ieee.org
• Chicago Manual of Style: https://www.chicagomanualofstyle.org