Categories Reference Guide
This guide is for versions Beta 36+
Library for Category-related operations.
An entity to which a variety of nodes (e.g. representing records or media)
is attached, with a positional attribute.
Categories also have "subcategory" and "see_also" relationships with other categories.
| name | arguments | returns |
|---|---|---|
| set_database | cls, db :NeoAccess | None |
IMPORTANT: this method MUST be called before using this class!
:param db: Database-interface object, created with the NeoAccess library
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| get_category_info | cls, category_uri :str | dict |
Return the Name and Remarks attached to the given Category. If not found, return None
:param category_uri:A string identifying the desired Category
:return: The Category's name (or a blank dictionary if not found)
EXAMPLE: {"uri": "123", "name": "Astronomy", "remarks": "except cosmology"}
|
||
| name | arguments | returns |
|---|---|---|
| is_root_category | cls, category_uri :str | bool |
Return True if the given ID corresponds to the ROOT Category, or False otherwise
:param category_uri: A string identifying the desired Category
:return: True if the given ID corresponds to the ROOT Category, or False otherwise
|
||
| name | arguments | returns |
|---|---|---|
| count_subcategories | cls, category_uri :str | int |
Return the number of (direct) Subcategories of the given Category
:param category_uri:A string identifying the desired Category
:return: The number of (direct) Subcategories of the given Category; possibly, zero
|
||
| name | arguments | returns |
|---|---|---|
| count_parent_categories | cls, category_uri :str | int |
Return the number of (direct) Subcategories of the given Category
:param category_uri:A string identifying the desired Category
:return: The number of (direct) parent categories of the given Category; possibly, zero
|
||
| name | arguments | returns |
|---|---|---|
| get_subcategories | cls, category_uri :str | [dict] |
Return all the (immediate) subcategories of the given category,
as a list of dictionaries with all the keys of the Category Class
EXAMPLE:
[{'uri': '2', 'name': 'Work', remarks: 'outside employment'},
{'uri': '3', 'name': 'Hobbies'}]
:param category_uri:A string identifying the desired Category
:return: A list of dictionaries
|
||
| name | arguments | returns |
|---|---|---|
| get_parent_categories | cls, category_uri :str | [dict] |
Return all the (immediate) parent categories of the given Category,
as a list of dictionaries with all the keys of the Category Class
EXAMPLE:
[{'uri': '2', 'name': 'Work', remarks: 'outside employment'}, {'uri': '3', 'name': 'Hobbies'}]
:param category_uri:A string identifying the desired Category
:return: A list of dictionaries
|
||
| name | arguments | returns |
|---|---|---|
| get_all_categories | cls, exclude_root=True, include_remarks=False | [dict] |
Return all the existing Categories - possibly except the root -
as a list of dictionaries with keys 'uri', 'name', 'pinned' and, optionally, 'remarks',
sorted by name.
:param exclude_root: If True, the root Category is omitted
:param include_remarks: If True, the 'remarks' property is included alongside all others
:return: A list of dictionaries. EXAMPLE:
[{'uri': '2', 'name': 'Work', 'remarks': 'Current or past'},
{'uri': '3', 'name': 'Hobbies', pinned: True} ]
|
||
| name | arguments | returns |
|---|---|---|
| get_sibling_categories | cls, category_internal_id: int | [dict] |
Return the data of all the "siblings" of the given Category
:param category_internal_id: The internal database ID of a "Category" data node
:return: A list of dictionaries, with one element for each "sibling";
each element contains the 'internal_id' and 'neo4j_labels' keys,
plus whatever attributes are stored on that node.
EXAMPLE of single element:
{'name': 'French', 'internal_id': 123, 'neo4j_labels': ['Categories', 'BA']}
|
||
| name | arguments | returns |
|---|---|---|
| create_parent_map | cls, category_uri :str | dict |
Consider the set comprising the given Category and all its ancestors (i.e. all its super-categories),
up to a maximum hop length.
Create and return a dictionary that maps each of the uri in that set of Categories,
to a list of the uri's of its parent Categories.
:param category_uri:A string identifying the desired Category
:return: A dictionary mapping integers into lists of integers.
The keys are uri's of the given Category and any of its ancestors (super-categories),
up to a maximum hop length;
the values are lists of the uri's of the parent categories of the Category specified by the key
EXAMPLES: {'123': ['1']} # The given category (123) is a child of the root (1)
{'823': ['709'], '709': ['544'], '544': ['1']} # A simple 3-hop path from Category 823 to the root (1) :
# 823 is subcategory of 709,
# which is subcategory of 544, which is subcategory of the root
{'814': ['20', '30'], '20': ['1'], '30': ['79'], '79': ['1']} # Two paths from Category 814 to the root;
# 814 is subcategory of 20 and 30;
# 20 is an subcategory of the root,
# while with 30 we have to go thru an extra hop
|
||
| name | arguments | returns |
|---|---|---|
| create_bread_crumbs | cls, category_uri :str | list |
Return a list of Category ID's together with token strings, providing directives for the HTML structure of
the bread crumbs
:param category_uri:A string with the URI of the Category whose "ancestry bread crumbs" we want to construct
:return: A list of Category URI's together with token strings,
providing directives for the HTML structure of the bread crumbs
EXAMPLE 1: ['1']
EXAMPLE 2: ['START_CONTAINER', ['1', 'ARROW', '799', 'ARROW', '876'], 'END_CONTAINER']
EXAMPLE 3:
[
'START_CONTAINER',
['START_BLOCK',
'START_LINE', ['1', 'ARROW', '799', 'ARROW', '526'], 'END_LINE', 'CLEAR_RIGHT',
'START_LINE', ['1', 'ARROW', '61'], 'END_LINE',
'END_BLOCK', 'ARROW', '814'],
'END_CONTAINER'
]
|
||
| name | arguments | returns |
|---|---|---|
| recursive | cls, category_uri :str, parents_map :dict | list |
:param category_uri:A string identifying the desired Category
:param parents_map: The dict structure returned by create_parent_map()
:return:
|
||
| name | arguments | returns |
|---|---|---|
| follow_see_also | cls, category_uri :str | [dict] |
From the given Category, follow all the "see also" links, and return data about them
:param category_uri:A string uniquely identifying an existing Category data node
:return: A (possibly empty) list of dictionaries
that contain the keys 'name', 'uri' and 'description'
Values for 'description' might be None. EXAMPLE:
[{'name': 'Quotes', 'uri': '823', 'description': None}]
|
||
| name | arguments | returns |
|---|---|---|
| create_categories_root | cls, data_dict=None | (int, str) |
Create a ROOT Category node;
and return its internal database ID and its URI
:param data_dict: (OPTIONAL) Dict to specify alternate desired values
for the "name" and "remarks" fields of the Root Category
(by default, "HOME" and "top level", respectively)
:return: The pair (internal database ID, string URI)
of the new Data Node just created
|
||
| name | arguments | returns |
|---|---|---|
| add_subcategory | cls, data_dict :dict | str |
Add a new Subcategory to a given, already existing, Category
:param data_dict: Dictionary with the following keys:
category_uri URI to identify the Category
to which to add the new Subcategory
subcategory_name The name to give to the new Subcategory
subcategory_remarks (OPTIONAL) A comment field for the new Subcategory
:return: A string with the auto-increment "uri" value of the Category node just created
|
||
| name | arguments | returns |
|---|---|---|
| delete_category | cls, uri :str | None |
Delete the specified Category, provided that there are no Content Items linked to it.
In case of error or failure, an Exception is raised.
:param uri: The uri identifying the desired Category
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| add_subcategory_relationship | cls, data_dict :dict | None |
Add a sub-category ("BA_subcategory_of") relationship
between the specified 2 existing Categories.
If the requested new relationship cannot be created (for example, if it already exists),
raise an Exception
:param data_dict: Two keys are expected:
"sub" URI to identify an existing Category node
that is to be made a sub-category of another one
"cat" URI to identify an existing Category node
that is to be made the parent of the other Category
:return: None. If the requested new relationship could not be created,
raise an Exception
|
||
| name | arguments | returns |
|---|---|---|
| add_relationship_before | cls, from_id :str, to_id :str, rel_name :str | None |
A handler to be invoked by the core module before a relationship involving Categories is called.
If any restriction would apply to adding the parent/child relationship between the specified categories,
raise an Exception.
IMPORTANT: NO RELATIONSHIP IS ACTUALLY ADDED
The restriction are:
1) the subcategory node cannot be the Root Category
2) a category cannot be a subcategory of itself
NOTE: the "BA_subcategory_of" relationship goes FROM the subcategory TO the parent category node
:param from_id: String with the uri of the subcategory node
:param to_id: String with the uri of the parent-category node
:param rel_name: NOT USED
:return: None. If the requested new relationship should not be created, raise an Exception
|
||
| name | arguments | returns |
|---|---|---|
| remove_relationship_before | cls, from_id: str, to_id :str, rel_name: str | None |
A handler to be invoked by the core module before a relationship involving Categories is called.
If any restriction would apply to removing the parent/child relationship between the specified categories,
raise an Exception.
IMPORTANT: NO RELATIONSHIP IS ACTUALLY REMOVED
The restriction is:
*) the subcategory node cannot become orphaned as a result of the deletion
NOTE: the "BA_subcategory_of" relationship goes FROM the subcategory TO the parent category node
:param from_id: String with the uri of the subcategory node
:param to_id: NOT USED. String with the uri of the parent-category node
:param rel_name: NOT USED
:return: None. If the requested new relationship should not be deleted, raise an Exception
|
||
| name | arguments | returns |
|---|---|---|
| switch_parent_category_relationship | cls, child_id :str, old_parent_id :str, new_parent_id :str | None |
NOT YET IMPLEMENTED!
Switch a parent/child relationship between the specified categories.
Take the child away from the old parent, and re-assign to the new one.
:param child_id:
:param old_parent_id:
:param new_parent_id:
:return:
|
||
| name | arguments | returns |
|---|---|---|
| switch_subcategory_relationship | cls, parent_id :str, old_child_id :str, new_child_id :str | None |
NOT YET IMPLEMENTED!
Switch a parent/child relationship between the specified categories.
From the parent, take the old child away , and replace it with the new child.
:param parent_id:
:param old_child_id:
:param new_child_id:
:return:
|
||
| name | arguments | returns |
|---|---|---|
| pin_category | cls, uri, op :str | None |
Set or unset the "pinned" property of the specified Category
:param uri: The URI of a data node representing a Category
:param op: Either "set" or "unset"
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| is_pinned | cls, uri :str | bool |
Return True if the given Category has a "pinned" status; otherwise, False
:param uri: The URI of a data node representing a Category
:return: True or False
|
||
| name | arguments | returns |
|---|---|---|
| get_categories_linked_to_content_item | cls, item_uri :str | [{}] |
Locate and return information about all the Categories
that the given Content Item is linked to
:param item_uri: The URI of a data node representing a Content Item
:return: A list of dicts that have the keys "uri", "name", "remarks";
any missing value will appear as None
|
||
| name | arguments | returns |
|---|---|---|
| get_content_items_by_category | cls, category_uri = "1" | [{}] |
Return the records for all nodes linked
to the Category node identified by its uri value (by default, the ROOT Category)
:param category_uri:A string identifying the desired Category
:return: A list of dictionaries
EXAMPLE:
[{'schema_code': 'i', 'uri': '1','width': 450, 'basename': 'my_pic', 'suffix': 'PNG', pos: 0, 'class_name': 'Images'},
{'schema_code': 'h', 'uri': '1', 'text': 'Overview', pos: 10, 'class_name': 'Headers'},
{'schema_code': 'n', 'uri': '1', 'basename': 'overview', 'suffix': 'htm', pos: 20, 'class_name': 'Notes'}
]
|
||
| name | arguments | returns |
|---|---|---|
| add_content_at_beginning | cls, category_uri :str, item_class_name: str, item_properties: dict, new_uri=None | str |
Add a new Content Item, with the given properties and Class, to the beginning of the specified Category.
:param category_uri: The string "uri" of the Category to which this new Content Media is to be attached
:param item_class_name: For example, "Images"
:param item_properties: A dictionary with keys such as "width", "height", "caption","basename", "suffix"
:param new_uri: Normally, the Item ID is auto-generated, but it can also be provided (Note: MUST be unique)
:return: The auto-increment "uri" assigned to the newly-created data node
|
||
| name | arguments | returns |
|---|---|---|
| link_content_at_end | cls, category_uri :str, item_uri :str, label="BA" | None |
Given an EXISTING data node, link it to the end of the specified Category.
If a connection to that Category already exists, an Exception is raised.
:param category_uri:String to identify an existing Category
:param item_uri: String to identify an existing Content Item
:param label: (OPTIONAL) label required on the Content Item, to speed up the match
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| add_content_at_end | cls, category_uri :str, item_class_name: str, item_properties: dict, new_uri=None | str |
Add a NEW Content Item, with the given properties and Class, to the end of the specified Category.
First, create a new Data Node, and then link it to the given Category, positioned at the end.
:param category_uri: A string to identify the Category
to which this Content Media being newly-created is to be attached
:param item_class_name: For example, "Images"
:param item_properties: A dictionary with keys such as "width", "height", "caption","basename", "suffix"
:param new_uri: Normally, the Item ID is auto-generated, but it can also be provided (Note: MUST be unique)
:return: The "uri" (passed or created) of the newly-created data node
|
||
| name | arguments | returns |
|---|---|---|
| add_content_after_element | cls, category_uri :str, item_class_name: str, item_properties: dict, insert_after :str, new_uri=None | str |
Add a NEW Content Item, with the given properties and Class, inserted into the given Category after the specified Item
(in the context of the positional order encoded in the relationship attribute "pos")
:param category_uri: The string "uri" of the Category to which this new Content Media is to be attached
:param item_class_name: For example, "Images"
:param item_properties: A dictionary with keys such as "width", "height", "caption","basename", "suffix"
:param insert_after: The URI of the element after which we want to insert
:param new_uri: Normally, the Item ID is auto-generated, but it can also be provided (Note: MUST be unique)
:return: The auto-increment "uri" assigned to the newly-created data node
|
||
| name | arguments | returns |
|---|---|---|
| detach_from_category | cls, category_uri :str, item_uri :str | None |
Sever the link from the specified Content Item and the given Category.
If it's the only Category that the Content Item is currently linked to,
an Exception is raised (to avoid leaving that Content Item "stranded")
:param category_uri: The URI of a data node representing a Category
:param item_uri: The URI of a data node representing a Content Item
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| get_items_schema_data | cls, category_uri :str | dict |
Locate all the Classes used by Content Items attached to the given Category,
and return a dictionary with the Properties (in Schema order) of each,
including Properties of "ancestor" Classes (thru "INSTANCE_OF" relationships).
However, Properties marked as "system" are excluded
:param category_uri:A string identifying the desired Category
:return: A dictionary whose keys are Class names (of Content Items attached to the given Category),
and whose values are the Properties (in declared Schema order) of those Classes.
Properties declared in "ancestor" Classes (thru "INSTANCE_OF" relationships) are also included.
EXAMPLE:
{'German Vocabulary': ['Gender', 'German', 'English', 'notes'],
'Site Link': ['url', 'name', 'date', 'comments', 'rating', 'read'],
'Headers': ['text']}
|
||
| name | arguments | returns |
|---|---|---|
| check_for_duplicates | cls, category_uri :str | str |
Look for duplicates values in the "pos" attributes
of the "BA_in_category" relationships ending in the specified Category node (specified by its uri)
:param category_uri:A string identifying the desired Category
:return: In case of duplicates, return a text with an explanation;
if no duplicates, return an empty string
|
||
| name | arguments | returns |
|---|---|---|
| check_all_categories_for_duplicates | cls | str |
:return: In case of duplicates, return a text with an explanation;
if no duplicates, return an empty string
|
||
| name | arguments | returns |
|---|---|---|
| reposition_content | cls, category_uri :str, uri: str, move_after_n: int | |
Reposition the given Content Item after the n-th item (counting starts with 1) in specified Category.
Note: there's no harm (though it's wasteful) to move an item to a final sequence position where it already is;
its "pos" value will change
:param category_uri: A string identifying the desired Category
:param uri: A string with the URI of the Content Item we're repositioning
:param move_after_n: The index (counting from 1) of the item after which we want to position the item being moved
Use n=0 to indicate "move before anything else"
:return:
|
||
| name | arguments | returns |
|---|---|---|
| relocate_positions | cls, category_uri :str, n_to_skip: int, pos_shift: int | int |
Shift the values of the "pos" attributes on the "BA_in_category" relationships
from the given Category node, by the given amount;
however, SKIP the first n_to_skip entries (as sorted by the "pos" attribute)
EXAMPLE - given the following order of the relationships attached to the given Category:
pos
1: 45
2: 84
3: 91
then relocate_positions(category_uri, n_to_skip=1, pos_shift=100) will result in:
pos
1: 45 <= got skipped
2: 184
3: 191
:param category_uri:A string identifying the desired Category
:param n_to_skip: The number of relationships (after sorting them by "pos") NOT to re-position
Must be an integer >= 1 (it'd be pointless to shift everything!)
:param pos_shift: The increment by which to shift the values of the "pos" attributes on the relationships
:return: The number of repositionings performed
|
||
| name | arguments | returns |
|---|---|---|
| swap_content_items | cls, uri_1 :str, uri_2 :str, cat_id :str | None |
Swap the positions of the specified Content Items within the given Category
:param uri_1: A string with the uri of the 1st Content Item
:param uri_2: A string with the uri of the 2nd Content Item
:param cat_id: A string with the uri ID of the Category
:return: None. In case of error, raise an Exception
|
||
| name | arguments | returns |
|---|---|---|
| viewer_handler | cls, category_uri :str | |
Handler function for the Flask page generator "BA_pages_routing.py"
:param category_uri: A string identifying the desired Category
:return: A list of dictionaries, with one element for each "sibling";
each element contains the 'internal_id' and 'neo4j_labels' keys,
plus whatever attributes are stored on that node.
EXAMPLE of single element:
{'name': 'French', 'internal_id': 123, 'neo4j_labels': ['Categories', 'BA']}
|
||