From 86b99b69a73023ff93e809c9f8d581469354e8e1 Mon Sep 17 00:00:00 2001
From: Benjamin Renard <brenard@easter-eggs.com>
Date: Thu, 25 Jul 2019 14:05:37 +0200
Subject: [PATCH] Add doc-string about datetime helpers

---
 LdapServer.py | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/LdapServer.py b/LdapServer.py
index 42ec1e8..1f6a5b7 100644
--- a/LdapServer.py
+++ b/LdapServer.py
@@ -154,6 +154,15 @@ class LdapServerException(BaseException):
 # Helpers
 #
 def parse_datetime(value, to_timezone=None, default_timezone=None):
+	"""
+	Convert LDAP date string to datetime.datetime object
+
+	:param	value:			The LDAP date string to convert
+	:param	to_timezone:		If specified, the return datetime will be converted to this
+					specific timezone (optional, default : timezone of the LDAP date string)
+	:param	default_timezone:	The timezone used if LDAP date string does not specified
+					the timezone (optional, default : server local timezone)
+	"""
 	assert to_timezone is None or isinstance(to_timezone, datetime.tzinfo) or isinstance(to_timezone, str), 'to_timezone must be None, a datetime.tzinfo object or a string (not %s)' % type(to_timezone)
 	assert default_timezone is None or isinstance(default_timezone, datetime.tzinfo) or isinstance(default_timezone, pytz.tzinfo.DstTzInfo) or isinstance(default_timezone, str), 'default_timezone parameter must be None, a string, a pytz.tzinfo.DstTzInfo or a datetime.tzinfo object (not %s)' % type(default_timezone)
 	date = dateutil.parser.parse(value, dayfirst=False)
@@ -175,9 +184,26 @@ def parse_datetime(value, to_timezone=None, default_timezone=None):
 	return date
 
 def parse_date(value, to_timezone=None, default_timezone=None):
+	"""
+	Convert LDAP date string to datetime.date object
+
+	:param	value:			The LDAP date string to convert
+	:param	to_timezone:		If specified, the return datetime will be converted to this
+					specific timezone (optional, default : timezone of the LDAP date string)
+	:param	default_timezone:	The timezone used if LDAP date string does not specified
+					the timezone (optional, default : server local timezone)
+	"""
 	return parse_datetime(value, to_timezone, default_timezone).date()
 
 def format_datetime(value, from_timezone=None, to_timezone=None):
+	"""
+	Convert datetime.datetime object to LDAP date string
+
+	:param	value:			The datetime.datetime object to convert
+	:param	from_timezone:		The timezone used if datetime.datetime object is naive (no tzinfo)
+					(optional, default : server local timezone)
+	:param	to_timezone:		The timezone used in LDAP (optional, default : UTC)
+	"""
 	assert isinstance(value, datetime.datetime), 'First parameter must be an datetime.datetime object (not %s)' % type(value)
 	assert from_timezone is None or isinstance(from_timezone, datetime.tzinfo) or isinstance(from_timezone, pytz.tzinfo.DstTzInfo) or isinstance(from_timezone, str), 'from_timezone parameter must be None, a string, a pytz.tzinfo.DstTzInfo or a datetime.tzinfo object (not %s)' % type(from_timezone)
 	assert to_timezone is None or isinstance(to_timezone, datetime.tzinfo) or isinstance(to_timezone, str), 'to_timezone must be None, a datetime.tzinfo object or a string (not %s)' % type(to_timezone)
@@ -205,6 +231,14 @@ def format_datetime(value, from_timezone=None, to_timezone=None):
 	return datestring
 
 def format_date(value, from_timezone=None, to_timezone=None):
+	"""
+	Convert datetime.date object to LDAP date string
+
+	:param	value:			The datetime.date object to convert
+	:param	from_timezone:		The timezone used if datetime.datetime object is naive (no tzinfo)
+					(optional, default : server local timezone)
+	:param	to_timezone:		The timezone used in LDAP (optional, default : UTC)
+	"""
 	assert isinstance(value, datetime.date), 'First parameter must be an datetime.date object (not %s)' % type(value)
 	return format_datetime(datetime.datetime.combine(value, datetime.datetime.min.time()), from_timezone, to_timezone)