Added documentation

paramecio2/libraries/datetime.py

@@ -6,14 +6,30 @@ from settings import config
 #from paramecio.citoplasma.sessions import get_session
 from os import environ
 
+"""Simple hook for timedate functions from Arrow datetime module
+"""
 
 sql_format_time='YYYYMMDDHHmmss'
+"""str: variable for define basic string for format dates
+
+
+By default, datetime module use YYYYMMDDHHmmss string for define dates and time. Tipically is used for sql operations in paramecio2 framework.
+"""
 
 format_date_txt="YYYY/MM/DD"
+"""str: variable for define basic formatted date string
+"""
 
 format_time_txt="HH:mm:ss"
+"""str: variable for define basic formatted time string
+"""
 
 timezone='Europe/Madrid'
+"""str: basic timezone for dates, by default, Europe/Madrid
+"""
+
+"""If default are changed in settings/config, change variables
+"""
 
 if hasattr(config, 'format_date'):
     format_date_txt=config.format_date
@@ -25,6 +41,8 @@ if hasattr(config, 'timezone'):
     timezone=config.timezone    
 
 def set_timezone():
+    """Simple function for change the timezone in general environment of python
+    """
     
     environ['TZ']=environ.get('TZ', timezone)
     
@@ -54,6 +72,15 @@ def set_timezone_session():
 """
 
 def format_timedata(time):
+    """Function for get separated year, month, day, hour, minute and second from sql_format_time string
+    
+    Args:
+        time (str): A YYYYMMDDHHmmss string for get datetime components from there.
+     
+    Returns:
+        list: A dict with datetime components (year, month, day, hour, minute, second).
+    
+    """
     
     year=0
     month=0
@@ -90,6 +117,20 @@ def format_timedata(time):
     return (year, month, day, hour, minute, second)
 
 def checkdatetime(y, m, d, h, mi, s):
+    """Check if a series of datetime separated elements are correct, the datetime values are type int
+    
+    Args:
+        y (int): Year of datetime
+        m (int): month 
+        d (int): day
+        h (int): hour
+        mi (int): minute
+        s (int): seconds
+        
+    Returns:
+        bool: If values are correct, return True, otherwise return False
+    
+    """
     
     try:
         #test=datetime.strptime(str(y)+'-'+str(m)+'-'+str(d)+' '+str(h)+'-'+str(mi)+'-'+str(s), '%Y-%m-%d %H-%M-%S')
@@ -101,19 +142,16 @@ def checkdatetime(y, m, d, h, mi, s):
 # Get the localtime
     
 def now(utc=False, tz=''):
-    """
-    actual=datetime.today()
     
-    # Get localtime
+    """Returns the actual datetime in YYYYMMDDHHmmss format. 
     
-    final_date=actual.strftime(sql_format_time)
+    Args:
-    #Go to gmt
+        utc (bool): If True, the datetime is returned in UTC timezone
+        tz (str): Timezone name, example: Europe/Madrid. If set the datetime is returned in the timezone selected
     
-    if utc:
+    Returns:
+        str: Return actual datetime
     
-        final_date=local_to_gmt(final_date)
-        
-    return final_date
     """
         
     if not utc:
@@ -130,11 +168,35 @@ def now(utc=False, tz=''):
     
 def today(utc=False,tz=''):
     
+    """Returns the actual date in YYYYMMDDHHmmss format. 
+    
+    Is different from (now) function because return the date to 00:00:00 time
+    
+    Args:
+        utc (bool): If True, the date is returned in UTC timezone
+        tz (str): Timezone name, example: Europe/Madrid. If set the date is returned in the timezone selected
+    
+    Returns:
+        str: Return actual date with 00:00:00 how time
+    
+    """
+    
     return now(utc, tz)[:8]+'000000'
     
 # Get actual timestamp
 
-def obtain_timestamp(timeform, local=False, tz=''):
+def obtain_timestamp(timeform):
+    
+    """Get the timestamp from datetime in YYYYMMDDHHmmss format. 
+    
+    Args:
+        timeform (str): Datetime in YYYYMMDDHHmmss format. 
+    
+    Returns:
+    
+        int: datetime in timestamp format
+    
+    """
     
     y, m, d, h, mi, s=format_timedata(timeform)
     
@@ -142,21 +204,7 @@ def obtain_timestamp(timeform, local=False, tz=''):
         
         #timestamp=int(time.mktime((y, m, d, h, mi, s, 0, 0, -1)))       
         
-        if local:
+        timestamp=arrow.arrow.Arrow(y, m, d, h, mi, s).timestamp()
-            
-            #offset=time.altzone
-        
-            #return timestamp-offset
-            
-            if tz=='':
-                tz=environ.get('TZ', 'utc')
-            
-            t=arrow.arrow.Arrow(y, m, d, h, mi, s).to(tz)
-            
-            timestamp=t.timestamp()
-            
-        else:
-            timestamp=arrow.arrow.Arrow(y, m, d, h, mi, s).timestamp()
          
         return timestamp
         
@@ -168,19 +216,32 @@ def obtain_timestamp(timeform, local=False, tz=''):
 
 def timestamp_to_datetime(timestamp):
     
-    #time_set=substract_utc(timestamp)
+    """Turn datetime in YYYYMMDDHHmmss format. 
     
-    #return time.strftime(sql_format_time, time_set)
+    Args:
+        timestamp (int): The timestamp for convert
+        
+    Returns:
+        str: Datetime in YYYYMMDDHHmmss format
+    
+    """
     
     return arrow.get(timestamp).format(sql_format_time)
 
 # Get a utc timestamp and convert to local
 
 def timestamp_to_datetime_local(timestamp, tz=''):
+    """Get a utc timestamp and convert to timezone datetime in YYYYMMDDHHmmss format. 
     
-    #time_set=time.localtime(timestamp)
+    Args:
+        timestamp (int): The timestamp for convert in datetime
+        tz (str): If you want convert to other timezone, set it.
         
-    #return time.strftime(sql_format_time, time_set)
+    Returns:
+    
+        str: Datetime in YYYYMMDDHHmmss format in selected timezone datetime
+    
+    """
     
     t=arrow.get(timestamp)