diff --git a/src/linkahead/common/models.py b/src/linkahead/common/models.py
index 1dbeb802311c7afaea2340af15e49537520ef57f..fe2be59ad5b042db23cc0a567476bf9aa03d99ad 100644
--- a/src/linkahead/common/models.py
+++ b/src/linkahead/common/models.py
@@ -765,11 +765,18 @@ class Entity:
this method will created a new message from the parameters type, code,
description, and body.
- @param msg: The message to be added to this entity.
- @param type: The type of the message to be added.
- @param code: The code of the message to be added.
- @param description: The description of the message to be added.
- @param body: The body of the message to be added.
+ Parameters
+ ----------
+ msg : string
+ The message to be added to this entity.
+ type :
+ The type of the message to be added.
+ code :
+ The code of the message to be added.
+ description :
+ The description of the message to be added.
+ body :
+ The body of the message to be added
"""
if msg is not None:
@@ -874,7 +881,7 @@ class Entity:
Returns
-------
- out: bool
+ bool
True if ``parent`` is a true parent, False otherwise.
"""
@@ -900,10 +907,13 @@ class Entity:
return name_result and id_result
- def get_parents(self):
+ def get_parents(self)->ParentList:
"""Get all parents of this entity.
- @return: ParentList(list)
+ Returns
+ -------
+ ParentList
+ list of parents
"""
return self.parents
@@ -919,7 +929,7 @@ class Entity:
Returns
-------
- out: list[Entity]
+ list[Entity]
The parents of this Entity
"""
@@ -934,9 +944,15 @@ class Entity:
As a side effect of this method, the ancestors are added to
all_parents.
- @param all_parents: list, The added parents so far.
+ Parameters
+ ----------
+ all_parents: list
+ The added parents so far.
- @return: None, but see side effects.
+ Returns
+ -------
+ None
+ but see side effects.
"""
for parent in self.parents:
@@ -1003,7 +1019,10 @@ class Entity:
def get_properties(self):
"""Get all properties of this entity.
- @return: PropertyList(list)
+ Returns
+ -------
+ PropertyList
+ list of properties
"""
return self.properties
@@ -1019,7 +1038,7 @@ class Entity:
Returns
-------
- property : Property
+ Property
The first Property of this Entity with a matching name or id.
"""
@@ -1163,7 +1182,10 @@ class Entity:
def get_messages(self):
"""Get all messages of this entity.
- @return: Messages(list)
+ Returns
+ -------
+ Messages
+ list of messages
"""
return self.messages
@@ -1171,7 +1193,10 @@ class Entity:
def get_warnings(self):
"""Get all warning messages of this entity.
- @return Messages(list): Warning messages.
+ Returns
+ -------
+ Messages:
+ Warning messages.
"""
ret = Messages()
@@ -1184,7 +1209,10 @@ class Entity:
def get_errors(self):
"""Get all error messages of this entity.
- @return Messages(list): Error messages.
+ Returns
+ -------
+ Messages
+ Error messages.
"""
ret = Messages()
@@ -1201,8 +1229,11 @@ class Entity:
"""Get all error messages of this entity and all sub-entities /
parents / properties.
- @return A list of tuples. Tuple index 0 contains the error message
- and tuple index 1 contains the tree.
+ Returns
+ -------
+ list[tuple[str, list[Entity]]]
+ A list of tuples. Tuple index 0 contains the error message
+ and tuple index 1 contains the tree.
"""
roots = [] if roots is None else roots
result_list = list()
@@ -1219,7 +1250,10 @@ class Entity:
def has_errors(self):
'''
- @return True: if and only if this entities has any error messages.
+ Returns
+ -------
+ bool
+ True: if and only if this entities has any error messages.
'''
for m in self.messages:
@@ -1247,7 +1281,10 @@ class Entity:
FIXME: Add documentation for the add_properties parameter.
FIXME: Add docuemntation for the local_serialization parameter.
- @return: xml representation of this entity.
+ Returns
+ -------
+ etree._Element
+ xml representation of this entity.
"""
if xml is None:
@@ -1509,11 +1546,16 @@ class Entity:
returns a Container object which carries the returned entities. They are
distinct from this one. This entity will no be changed somehow.
- @param unique=True: flag to suppress the ambiguity exception.
+ Parameters
+ ----------
+ unique : bool =True
+ flag to suppress the ambiguity exception.
- @return
- Container with the returned entities or single entity if and only
- if unique was True and no exception was raised.
+ Returns
+ -------
+ Container
+ Container with the returned entities or single entity if and only
+ if unique was True and no exception was raised.
"""
@@ -1606,7 +1648,10 @@ class Entity:
anyway. Set flag 'strict' to True in order to force the server to take all warnings as
errors. This prevents the server from updating this entity if any warnings occur.
- @param strict=False: Flag for strict mode.
+ Parameters
+ ----------
+ strict: bool = False
+ Flag for strict mode.
"""
return Container().append(self).update(
@@ -2252,23 +2297,7 @@ class File(Record):
look at `test_files.py` in the Python integration tests of the
`load_files.py` script in the advanced user tools.
- @param name: A name for this file record (That's an entity name - not to be
- confused with the last segment of the files path).
- @param id: An ID.
- @param description: A description for this file record.
- @param path: The complete path, including the file name, of the file in the
- server's "caosroot" file system.
- @param file: A local path or python file object. The file designated by
- this argument will be uploaded to the server via HTTP.
- @param pickup: A file/folder in the DropOffBox (the server will move that
- file into its "caosroot" file system).
- @param thumbnail: (Local) filename to a thumbnail for this file.
- @param properties: A list of properties for this file record. @todo is this
- implemented?
- @param from_location: Deprecated, use `pickup` instead.
-
- """
-
+"""
def __init__(
self,
name: Optional[str] = None,
@@ -2280,6 +2309,33 @@ class File(Record):
thumbnail: Optional[str] = None,
from_location=None,
):
+ """
+ Parameters
+ ----------
+ name: str
+ A name for this file record (That's an entity name - not to be
+ confused with the last segment of the files path).
+ id: Union[str, int]
+ An ID.
+ description: str
+ A description for this file record.
+ path: str
+ The complete path, including the file name, of the file in the
+ server's "caosroot" file system.
+ file: Union[str, file]
+ A local path or python file object. The file designated by
+ this argument will be uploaded to the server via HTTP.
+ pickup: str
+ A file/folder in the DropOffBox (the server will move that
+ file into its "caosroot" file system).
+ thumbnail: str
+ (Local) filename to a thumbnail for this file.
+ properties: list[Property]
+ A list of properties for this file record. @todo is this
+ implemented?
+ from_location: str
+ Deprecated, use `pickup` instead.
+ """
Record.__init__(self, id=id, name=name, description=description)
self.role = "File"
self.datatype = None
@@ -2308,7 +2364,10 @@ class File(Record):
) -> etree._Element:
"""Convert this file to an xml element.
- @return: xml element
+ Returns
+ -------
+ etree.Element
+ xml element
"""
if xml is None:
@@ -2321,8 +2380,15 @@ class File(Record):
"""Download this file-entity's actual file from the file server. It
will be stored to the target or will be hold as a temporary file.
- @param target: Where to store this file.
- @return: local path of the downloaded file.
+ Parameters
+ ----------
+ target: Optional[str]
+ Where to store this file.
+
+ Returns
+ -------
+ str
+ local path of the downloaded file.
"""
self.clear_server_messages()
@@ -2434,8 +2500,14 @@ class PropertyList(list):
"""Get a property of this list via it's name. Raises a LinkAheadException
if not exactly one property has this name.
- @param name: the name of the property to be returned.
- @return: A property
+ Parameters
+ ----------
+ name: str
+ the name of the property to be returned.
+ Returns
+ -------
+ Entity
+ A property
"""
return self._element_by_name[name]
@@ -2541,8 +2613,14 @@ class PropertyList(list):
'''
Get the first entity which has the given cuid.
Note: this method is intended for internal use.
- @param name: The cuid of the entity to be returned.
- @return: Entity with the given cuid.
+ Parameters
+ ----------
+ name: str
+ The cuid of the entity to be returned.
+ Returns
+ -------
+ Entity
+ Entity with the given cuid.
'''
for e in self:
@@ -2599,8 +2677,15 @@ class ParentList(list):
'''
Get the first entity which has the given cuid.
Note: this method is intended for internal use.
- @param name: The cuid of the entity to be returned.
- @return: Entity with the given cuid.
+ Parameters
+ ----------
+ name: str
+ The cuid of the entity to be returned.
+
+ Returns
+ -------
+ Entity
+ Entity with the given cuid.
'''
for e in self:
@@ -3136,8 +3221,14 @@ class Container(list):
'''
Get the first entity which has the given cuid.
Note: this method is intended for internal use.
- @param name: The cuid of the entity to be returned.
- @return: Entity with the given cuid.
+ Parameters
+ ----------
+ name: str
+ The cuid of the entity to be returned.
+ Returns
+ -------
+ Entity
+ Entity with the given cuid.
'''
for e in self:
@@ -3152,8 +3243,14 @@ class Container(list):
entities are in this list which have the same id, this method will only
return the first and ignore the others.
- @param name: The id of the entity to be returned.
- @return: Entity with the given id.
+ Parameters
+ ----------
+ id: Union[int, str]
+ The id of the entity to be returned.
+ Returns
+ -------
+ Entity
+ Entity with the given id.
"""
for e in self:
@@ -3185,9 +3282,16 @@ class Container(list):
entities are in this list which have the same name, this method will
only return the first and ignore the others.
- @param name: the name of the entity to be returned.
- @param case_sensitive (True/False): Do a case-sensitive search for name (or not).
- @return: Entity with the given name.
+ Parameters
+ ----------
+ name: str
+ the name of the entity to be returned.
+ case_sensitive: bool
+ Do a case-sensitive search for name (or not).
+ Returns
+ -------
+ Entity
+ Entity with the given name.
"""
for e in self:
@@ -3305,7 +3409,10 @@ class Container(list):
def get_errors(self):
"""Get all error messages of this container.
- @return Messages: Error messages.
+ Returns
+ -------
+ Messages
+ Error messages.
"""
if self.has_errors():
@@ -3322,7 +3429,10 @@ class Container(list):
def get_warnings(self):
"""Get all warning messages of this container.
- @return Messages: Warning messages.
+ Returns
+ -------
+ Messages
+ Warning messages.
"""
if self.has_warnings():
@@ -3351,7 +3461,10 @@ class Container(list):
def has_warnings(self):
'''
- @return True: if and only if this container has any warning messages.
+ Returns
+ -------
+ bool
+ True if and only if this container has any warning messages.
'''
for m in self.messages:
@@ -3362,7 +3475,10 @@ class Container(list):
def has_errors(self):
'''
- @return True: if and only if this container has any error messages.
+ Returns
+ -------
+ bool
+ True if and only if this container has any error messages.
'''
for m in self.messages:
@@ -3389,7 +3505,10 @@ class Container(list):
def from_xml(xml_str):
"""Creates a Container from the given xml string.
- @return The created Container.
+ Returns
+ -------
+ Container
+ The created Container.
"""
c = Container()
@@ -3669,7 +3788,7 @@ class Container(list):
Returns
-------
- out : set
+ set
A set of IDs of unique elements that are a dependency of another element of ``container``.
"""
item_id = set()
@@ -5244,8 +5363,14 @@ def parse_xml(xml: Union[str, etree._Element]):
"""parse a string or tree representation of an xml document to a set of
entities (records, recordtypes, properties, or files).
- @param xml: a string or tree representation of an xml document.
- @return: list of entities or single entity.
+ Parameters
+ ----------
+ xml: Union[str, etree._Element]
+ a string or tree representation of an xml document.
+ Returns
+ -------
+ Union[Entity, list[Entity]
+ list of entities or single entity.
"""
if isinstance(xml, etree._Element):