Surf mappings

hucitlib relies on SuRF , a Python Object RDF Mapper library, so as to In order to make the knowledge base as much as possible easy to use programmatically. SuRF works similarly to Object-relation mappers (such as SQLAlchemy) with the main difference that Python objects are mapped to contents of a triples store rather than of a database.

A set of SuRF <https://pythonhosted.org/SuRF/> mappings is defined in order to ease the programmatic interaction with the knowledge base, and to away certain complexities of the underlying Data model.

Mappings are defined for the following classes:

frbroo:F10_Person -> HucitAuthor
frbroo:F1_Work -> HucitWork
hucit:TextElement -> HucitTextElement
hucit:TextStructure -> HucitTextStructure

Authors

class hucitlib.surfext.HucitAuthor

Object mapping for class frbroo:F10_Person.

add_abbreviation(new_abbreviation) → bool

Adds a new name abbreviation to an author’s name.

Parameters: new_abbreviation – the abbreviation to be added
Returns: True if the abbreviation is added, False otherwise (the abbreviation is a duplicate)

add_name(name: str, lang: Optional[str] = None) → bool

Adds a new name variant to an author’s name.

Parameters

name (str) – The name variant to be added.
lang (str) – The language of the name variant.

Returns

True if the name is added, False otherwise (the name is a duplicate)

Return type

bool

get_abbreviations() → List[str]

Get abbreviations of the names of the author.

Returns: A list of known abbreviations.
Return type: List[str]

Example:

>>> kb = KnowledgeBase()
>>> homer = kb.get_resource_by_urn('urn:cts:greekLit:tlg0012')
>>> homer.get_abbreviations()
['Hom.']

get_names() → Dict[str, str]

Returns a list of author’s name variants.

Returns: A dictionary where key is the language and value is the name in that language.
Return type: Dict[str]

Example:

>>> homer = kb.get_resource_by_urn('urn:cts:greekLit:tlg0012')
>>> homer.get_names()
[('en', 'Homer'),
(None, 'Homeros'),
('la', 'Homerus'),
('fr', 'Homère'),
('it', 'Omero')]

get_urn() → Optional[pyCTS.CTS_URN]

Returns the author’s CTS URN.

Note

It is assumed that each HucitAuthor has only one CTS URN.

Returns: Description of returned object.
Return type: Optional[CTS_URN]

get_works() → List[hucitlib.surfext.HucitWork]: Returns a list of the works (intances of surf.Resource and HucitWork) attributed to a given author.

set_urn(urn: str) → Optional[pyCTS.CTS_URN]

Changes the CTS URN of the author or adds a new one (if no URN is assigned).

Parameters: urn (str) – The new CTS URN.
Returns: Description of returned object.
Return type: Optional[CTS_URN]

to_json() → None

Serialises a HucitAuthor to a JSON formatted string.

Note

This method will probably be deprecated in the near future.

Example:

>> homer = kb.get_resource_by_urn("urn:cts:greekLit:tlg0012")
>> homer.to_json()
{
  "name_abbreviations": [
    "Hom."
  ],
  "urn": "urn:cts:greekLit:tlg0012",
  "works": [
    {
      "urn": "urn:cts:greekLit:tlg0012.tlg001",
      "titles": [
        {
          "language": "it",
          "label": "Iliade"
        },
        {
          "language": "la",
          "label": "Ilias"
        },
        {
          "language": "en",
          "label": "Iliad"
        },
        {
          "language": "de",
          "label": "Ilias"
        },
        {
          "language": "fr",
          "label": "L'Iliade"
        }
      ],
      "uri": "http://purl.org/hucit/kb/works/2815",
      "title_abbreviations": [
        "Il."
      ]
    },
    ...
  ],
  "uri": "http://purl.org/hucit/kb/authors/927",
  "names": [
    {
      "language": "fr",
      "label": "Homère"
    },
    {
      "language": "la",
      "label": "Homerus"
    },
    {
      "language": null,
      "label": "Homeros"
    },
    {
      "language": "en",
      "label": "Homer"
    },
    {
      "language": "it",
      "label": "Omero"
    }
  ]
}

Works

class hucitlib.surfext.HucitWork

Object mapping for instances of http://erlangen-crm.org/efrbroo/F1_Work.

add_abbreviation(new_abbreviation)

Adds a new name variant to a work.

Parameters: new_abbreviation – the abbreviation to be added
Returns: True if the abbreviation is added, False otherwise (the abbreviation is a duplicate)

add_text_structure(label: str, lang: str = 'en'): Adds a citable text structure to the work.

add_title(title, lang=None)

Adds a new title variant to a work.

Parameters

title – the title to be added
lang – the language of the title variant

Returns

True if the title is added, False otherwise (the title is a duplicate)

property author: hucitlib.surfext.HucitAuthor

Returns the author to whom the work is attributed.

Returns: an instance of HucitWork # TODO: check that’s the case

get_abbreviations(combine=False)

TODO: if combine==True, concatenate with author abbreviation(s)

Get abbreviations of the titles of the work.

Returns: a list of strings (empty list if no abbreviations available).

get_citation_structure() → List[hucitlib.surfext.CitationLevel]

Returns a sorted list of citation levels

[: (1, ‘book’, …), (2, ‘line’, …),

]

get_titles(): TODO

get_top_elements(): TODO

get_urn()

Get the CTS URN that identifies the work.

Returns: an instance of pyCTS.CTS_URN or None

has_text_structure()

Checks whether a citable text structure is defined.

Returns: boolean

is_opus_maximum()

Check whether the work is the author’s opus maximum.

Two cases: 1. the work is flagged as opus max 2. there is only one work by this author

Returns: boolean

remove_text_structure(text_structure) → None: Remove any citable text structure to the work.

set_as_opus_maximum(): Mark explicitly the work as the author’s opus maximum.

set_urn(urn): Change the CTS URN of the author or adds a new one (if no URN is assigned).

to_json(): Serialises a HucitWork to a JSON formatted string.

Citable text structures and text elements

class hucitlib.surfext.HucitTextStructure

Object mapping for instances of http://purl.og/net/hucit#TextStructure.

property work: Returns the parent object (HucitWork).

class hucitlib.surfext.HucitTextElement

Object mapping for instances of http://purl.og/net/hucit#TextElement.

add_relations(parent: surf.resource.Resource = None, previous: surf.resource.Resource = None, next: surf.resource.Resource = None) → None

Short summary.

Parameters

parent (Resource) – Description of parameter parent.
previous (Resource) – Description of parameter previous.
next (Resource) – Description of parameter next.

Returns

Description of returned object.

Return type

None

property children: List[surf.resource.Resource]: Returns the children text element(s) (if any).

get_type(as_string: bool = True) → Union[str, surf.resource.Resource]

Short summary.

Parameters: as_string (bool) – Description of parameter as_string.
Returns: Description of returned object.
Return type: Union[str, Resource]

get_urn() → pyCTS.CTS_URN: Returns the TextElement’s CTS URN.

property next: Optional[surf.resource.Resource]: Returns the following text element (if any).

property parent: Returns the parent (if any).

property previous: Returns the preceding text element (if any).