Functions

Most of CiteURL's core features can be accessed through the Citator class. But if you plan to perform multiple operations with the same set of citations, you can use these module-wide functions without generating a whole new list of citations every time.

Given a text and a list of citations found in it, return a text with an HTML hyperlink inserted for each citation.

Parameters:

Name Type Description Default
citations list

A list of citation objects found in the text

required
text str

The text the citations were found in

required
attrs dict

HTML tag attributes (like css class, rel, etc) to give each inserted hyperlink.

{'class': 'citation'}
link_detailed_ids bool

Whether to insert hyperlinks for citations like "Id. at 30."

True
link_plain_ids bool

Whether to insert hyperlinks for simple repeat citations like "id."

False
url_optional bool

Whether to insert link elements for citations that do not have an associated URL

False

Returns:

Type Description
str

The input text, with HTML links inserted for each citation

Source code in citeurl/__init__.py
def insert_links(
    citations: list,
    text: str,
    attrs: dict={'class': 'citation'},
    link_detailed_ids: bool=True,
    link_plain_ids: bool=False,
    url_optional: bool=False
) -> str:
    """
    Given a text and a list of citations found in it, return a text
    with an HTML hyperlink inserted for each citation.

    Arguments:
        citations: A list of citation objects found in the text
        text: The text the citations were found in
        attrs: HTML tag attributes (like css class, rel, etc)
            to give each inserted hyperlink.
        link_detailed_ids: Whether to insert hyperlinks for citations
            like "Id. at 30."
        link_plain_ids: Whether to insert hyperlinks for simple repeat
            citations like "id."
        url_optional: Whether to insert link elements for citations that
            do not have an associated URL
    Returns:
        The input text, with HTML links inserted for each citation
    """
    offset = 0
    for citation in citations:
        if not citation.URL and not url_optional:
            continue
        if citation.schema.is_id:
            if citation.schema._compiled_re().groupindex:
                if not link_detailed_ids:
                    continue
            elif not link_plain_ids:
                continue
        link = citation.get_link(attrs=attrs)
        cite_start = citation.span[0] + offset
        cite_end = citation.span[1] + offset
        text = ''.join([text[:cite_start], link, text[cite_end:]])
        offset += len(link) - len(citation.text)
    return text

list_authorities()

Combine a list of citations into a list of authorities, each of which represents all the citations to a particular source.

As a side-effect, this also gives each citation an authority attribute referring to the proper authority.

Parameters:

Name Type Description Default
citations list

The list of citations to combine

required
unimportant_tokens

A list of tokens whose values may differ among citations to the same authority.

required

Returns:

Type Description
list

A list of authority objects, sorted by the number of citations that refer to each, from most to least.

Source code in citeurl/__init__.py
def list_authorities(
    citations: list, 
    irrelevant_tokens: list=NON_AUTHORITY_TOKENS
) -> list:
    """
    Combine a list of citations into a list of authorities, each
    of which represents all the citations to a particular source.

    As a side-effect, this also gives each citation an `authority`
    attribute referring to the proper authority.

    Arguments:
        citations: The list of citations to combine
        unimportant_tokens: A list of tokens whose values may 
            differ among citations to the same authority.
    Returns:
        A list of authority objects, sorted by the number of citations
        that refer to each, from most to least.
    """
    authorities = []
    for citation in citations:
        for authority in authorities:
            if authority.matches(citation):
                authority.include(citation)
                break
        else:
            authorities.append(Authority(citation, irrelevant_tokens))
    def authority_sort_key(authority):
        return 0 - len(authority.citations)
    return sorted(authorities, key=authority_sort_key)