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.
insert_links()
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.template.is_id:
if citation.template._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)