From 131e93c679767dfde40810ac49571fcd1add4b7d Mon Sep 17 00:00:00 2001 From: Antonio de la Rosa Date: Wed, 16 Mar 2022 01:21:33 +0100 Subject: [PATCH] Added more doctstrings to functions and classes --- paramecio2/libraries/generate_admin_class.py | 2 +- paramecio2/libraries/lists.py | 95 ++++++++++++++++++++ paramecio2/libraries/mtemplates.py | 8 ++ 3 files changed, 104 insertions(+), 1 deletion(-) diff --git a/paramecio2/libraries/generate_admin_class.py b/paramecio2/libraries/generate_admin_class.py index dcbaccb..23101d7 100644 --- a/paramecio2/libraries/generate_admin_class.py +++ b/paramecio2/libraries/generate_admin_class.py @@ -21,7 +21,7 @@ class GenerateAdminClass: t (PTemplate): Template used for the class. Normally template subclassed from admin_t PTemplate Attributes: - model (WebModel) The webmodel used for generatre the admin model form + model (WebModel) The webmodel used for generate the admin model form t (PTemplate): Template used for the class. Normally template subclassed from admin_t PTemplate list (SimpleList): A SimpleList class used for generate the listing arr_fields_edit (list): A list with the fields that the user can edit diff --git a/paramecio2/libraries/lists.py b/paramecio2/libraries/lists.py index 35f0678..d17ceb6 100644 --- a/paramecio2/libraries/lists.py +++ b/paramecio2/libraries/lists.py @@ -9,8 +9,46 @@ import sys import re class SimpleList: + """Class for create item list from a model table + """ def __init__(self, model, url, t): + """Class for create item list from a model table + + You can create lists using a WebModel. You can select the show fields, and you have features how order by field and simple searchs. + + Args: + model (WebModel): A WebModel model (equivalent to database mysql table) + url (str): A string with the base url for the forms. + t (PTemplate): Template used for the class. Normally template subclassed from admin_t PTemplate + + Attributes: + raw_query (boolean): If True then raw query is done, if False then query with all related fields is done + t (PTemplate): Template used for the class. Normally template subclassed from admin_t PTemplate + model (WebModel) The webmodel used for generate the admin model form + fields (list) A list with fields names of model getting of db query + fields_showed (list) A list with fields names of model showed in list + url (str): Base url used by SimpleList for generate edit, insert and other urls. + limit_pages (int): The number of items by page. By default, 20 items + order_defaults (list): Internal list used for define Ascendent and Descendent in sql queries + order_class (list): Internal list used for show icons for ascendent or descendent field selection + order (str): Default order used in order_defaults list + order_field (str): The default field used for order the list. By default is the model id field + order_by (str): The default order ASC or DESC defined in order_class list. By default is 0 or ASC + change_order (dict): Internal dict used for get all ordenable fields from model + yes_search (boolean): If True, a search form is showed, if False, the search form is hidden. + search_text (str): Used for save the search text sended via POST. + initial_num_pages (int): Initial number of pages showed in pagination. + table_div (boolean): If True, use div for create the table, if False, use standard html table for create the table. + begin_page (int): Number that is used for begin the elements to get from query + search_fields (list): The fields used for search data in form. + arr_extra_fields (list): List with the names of extra fields + arr_extra_options (list): List with a set of functions used how extra fields. This functions return lists with different options, joined with jln attribute. + jln (list): Jump line for join options by default. + ajax (boolean): If True, ajax is used for get items for the list and change page, if False, typical httpd request is used for change the items page. + + + """ self.raw_query=True @@ -78,9 +116,14 @@ class SimpleList: self.ajax=False def restore_fields(self): + """Simple method for restore default fields from model + """ + self.fields=self.model.fields.keys() def obtain_order(self): + """Function for set the order query defaults for list from http request query args. + """ #self.order=request.args.get('order', self.order) #self.getpostfiles.get.get('order', self.order) self.order=get_query_args('order', self.order) @@ -101,6 +144,8 @@ class SimpleList: self.order=order_k def obtain_field_search(self): + """Function for set the field search query defaults for list from http request query args. + """ self.order_field=get_query_args('order_field', self.order_field) @@ -134,6 +179,8 @@ class SimpleList: #self.order_field=self.order_field def search(self): + """Function for set the text order query defaults for list from http request query args. + """ self.search_text=get_query_args('search_text', '') @@ -153,17 +200,31 @@ class SimpleList: pass def set_options(self, options_func, arr_row): + """Method for join options list returns with jln attributte separator + + Returns: + str: Return a string with joined options + """ #SimpleList.standard_options(arr_row) return self.jln.join(options_func(self.url, arr_row[self.model.name_field_id], arr_row)) @staticmethod def standard_options(url, id, arr_row): + """Static method for get standar options for make things with the items row. + + Returns: + list: Return a list of basic options for items row + """ options=[] options.append(''+I18n.lang('common', 'edit', 'Edit')+'') options.append(''+I18n.lang('common', 'delete', 'Delete')+'') return options def show(self): + """Method for show the table + + The principal method of the class. The list is showed with the selected fields, search form, pagination... + """ self.model.yes_reset_conditions=False @@ -211,15 +272,19 @@ class SimpleList: return listing + """ @staticmethod def get_ajax_page(model): pass + """ class AjaxList(SimpleList): + """Class for make a list from a table based in Ajax + """ # Fields example: [[I18n.lang('cuchulu', 'hostname', 'Hostname'), True], ['IP', True], [I18n.lang('cuchulu', 'options', 'Options'), False]] @@ -232,6 +297,32 @@ class AjaxList(SimpleList): # str_query_params -> [s['cu_id'], begin_page, limit] def __init__(self, db, fields, arr_order_fields, count_query, str_query): + """Class for make a list from a table based in Ajax + + A class that is useful for creating listings based on database models using Ajax + + Args: + db (sql connection): A MySQL connection used for get the model. + fields (list): A list with the fields showed in table + arr_order_fields (list): A list with the sql names of selected fields for show. + count_query (str): sql segment for count query sentence. Example: select count(id) from table WHERE name=%s + str_query (str): sql segment for query sentence. Example: select id from table WHERE name=%s + + Attributes: + fields (list): A list with the fields showed in table + arr_order_fields (list): A list with the sql names of selected fields for show. + limit (int): the number of items selected in query sentence. + count_query (str): sql segment for count query sentence. Example: select count(id) from table WHERE name=%s + count_query_params (list): A list with the params for parse a sql count query with %s symbols (View python help about sql sentences and connectors) + str_query (str): sql segment for query sentence. Example: select id from table WHERE name=%s + str_query_params (list): A list with the params for parse a sql query with %s symbols (View python help about sql sentences and connectors) + initial_num_pages (int): Initial number of pages showed in pagination. + db (sql connection): A MySQL connection used for get the model. + func_fields (dict): A series of functions used for a series of extra fields referring to each row of the table + initial_order_field (str): FIeld used for order the table in first execution + initial_order (int): If 0, the initial order is Ascendent, if 1, the initial order is Descendent. + + """ self.fields=fields self.arr_order_fields=arr_order_fields @@ -248,6 +339,10 @@ class AjaxList(SimpleList): self.initial_order=0 def show(self): + """Method for show the table + + The principal method of the class. The list is showed with the selected fields, search form, pagination... + """ begin_page=int(get_query_args('position', 0)) order_field=get_query_args('order_field', self.initial_order_field) diff --git a/paramecio2/libraries/mtemplates.py b/paramecio2/libraries/mtemplates.py index 711d07d..bb78760 100644 --- a/paramecio2/libraries/mtemplates.py +++ b/paramecio2/libraries/mtemplates.py @@ -12,6 +12,14 @@ from paramecio2.libraries.urls import make_url, make_media_url, add_get_paramete from paramecio2.libraries.formsutils import csrf_token def env_theme(module, cache_enabled=True, cache_impl='', cache_args={}, module_directory="./tmp/modules"): + """Function for create an environment for mako templates + + Function for create an environment for mako templates. Really is a shortcut for TemplateLookup mako function. You can define cache options and module_directory for templates compiled + + Args: + module (str): The module where the templates can be founded + cache_enabled (boolean): If True + """ ext=module[len(module)-3:]