Added new tests and updated some functions

Author: domdfcoding

.travis.yml

@@ -5,7 +5,7 @@ python:
 - '3.7'
 - "3.8"
 install:
-- pip install -U coveralls pytest
+- pip install -U coveralls pytest pytz
 script:
 - coverage run --source=domdf_python_tools -m pytest
 after_success:

domdf_python_tools/dates.py

@@ -38,32 +38,92 @@
 try:
 	import pytz
 
-	def current_tzinfo():
+	
+	def get_utc_offset(tz, date=None):
 		"""
-		Returns a tzinfo object for the current timezone
+		Returns the offset between UTC and the requested timezone on the given date.
+		If ``date`` is ``None`` then the current date is used.
 		
-		:rtype: :class:`~python:datetime.tzinfo`
+		:param tz: :class:`pytz.timezone` or a string representing the timezone
+		:type tz:
+		:param date:
+		:type date: :class:`python:datetime.datetime` or None, optional
+		:return:
+		:rtype: :class:`python:datetime.timedelta`
 		"""
 
-		return datetime.datetime.now().astimezone().tzinfo
+		if date is None:
+			date = datetime.datetime.utcnow()
+		
+		if isinstance(tz, str):
+			tz = get_timezone(tz, date)
+		
+		return date.replace(tzinfo=pytz.utc).astimezone(tz).utcoffset()
 
 
-	def datetime_to_utc_timestamp(datetime, current_tzinfo=None):
+	def get_timezone(tz, date=None):
+		"""
+		Returns a localized :class:`pytz.timezone` object for the given date.
+		If ``date`` is ``None`` then the current date is used.
+
+		:param tz: A string representing a pytz timezone
+		:type tz:
+		:param date:
+		:type date: :class:`python:datetime.datetime` or None, optional
+		:return:
+		:rtype: :class:`python:datetime.timedelta`
 		"""
-		Convert a :class:`datetime.datetime` object to seconds since UNIX epoch, in UTC time
 
-		:param datetime:
-		:type datetime: :class:`datetime.datetime`
-		:param current_tzinfo: A tzinfo object representing the current timezone.
-			If None it will be inferred.
-		:type current_tzinfo: :class:`~python:datetime.tzinfo`
+		if date is None:
+			date = datetime.datetime.utcnow()
+			
+		d = date.replace(tzinfo=None)
+
+		return pytz.timezone(tz).localize(d).tzinfo
+	
+	
+	def current_tzinfo():
+		"""
+		Returns a tzinfo object for the current timezone
 		
-		:return: Timestamp in UTC timezone
-		:rtype: float
+		:rtype: :class:`python:datetime.tzinfo`
 		"""
 
-		return datetime.astimezone(current_tzinfo).replace(tzinfo=pytz.UTC).timestamp()
+		return datetime.datetime.now().astimezone().tzinfo
 
+	#
+	# def datetime_to_utc_timestamp(datetime, current_tzinfo=None):
+	# 	"""
+	# 	Convert a :class:`datetime.datetime` object to seconds since UNIX epoch, in UTC time
+	#
+	# 	:param datetime:
+	# 	:type datetime: :class:`datetime.datetime`
+	# 	:param current_tzinfo: A tzinfo object representing the current timezone.
+	# 		If None it will be inferred.
+	# 	:type current_tzinfo: :class:`~python:datetime.tzinfo`
+	#
+	# 	:return: Timestamp in UTC timezone
+	# 	:rtype: float
+	# 	"""
+	#
+	# 	return datetime.astimezone(current_tzinfo).timestamp()
+	#
+		
+	def set_timezone(obj, tzinfo):
+		"""
+		Sets the timezone / tzinfo of the given :class:`datetime.datetime` object.
+		This will not convert the time (i.e. the hours will stay the same).
+		Use :func:`python:datetime.datetime.astimezone` to accomplish that
+		:param obj:
+		:type obj:
+		:param tzinfo: 
+		:type tzinfo: 
+		:return: 
+		:rtype: 
+		"""
+		
+		return obj.replace(tzinfo=tzinfo)
+		
 
 	def utc_timestamp_to_datetime(utc_timestamp, output_tz=None):
 		"""
@@ -92,11 +152,7 @@ def utc_timestamp_to_datetime(utc_timestamp, output_tz=None):
 		"""
 
 		new_datetime = datetime.datetime.fromtimestamp(utc_timestamp, output_tz)
-		
-		if output_tz is None:
-			return new_datetime.astimezone()
-		else:
-			return new_datetime
+		return new_datetime.astimezone(output_tz)
 
 except ImportError:
 	import warnings

domdf_python_tools/doctools.py

@@ -30,33 +30,36 @@
 import builtins
 
 
-def document_object_from_another(target, original):
+def deindent_string(string):
 	"""
-	Sets the docstring of the `target` function to that of the `original` function.
+	Removes all indentation from the given string
 
-	This may be useful for subclasses or wrappers that use the same arguments.
+	:param string:
+	:type string: str
 
-	:param target: The object to set the docstring for
-	:type target: any
-	:param original: The object to copy the docstring from
-	:type original: any
+	:return:
+	:rtype: str
 	"""
 
-	target.__doc__ = original.__doc__
+	split_string = string.split("\n")
+	deindented_string = [line.lstrip("\t ") for line in split_string]
+	return "\n".join(deindented_string)
 
 
-def is_documented_by(original):
+# Functions that do the work
+def document_object_from_another(target, original):
 	"""
 	Sets the docstring of the `target` function to that of the `original` function.
 
 	This may be useful for subclasses or wrappers that use the same arguments.
+
+	:param target: The object to set the docstring for
+	:type target: any
+	:param original: The object to copy the docstring from
+	:type original: any
 	"""
 
-	def wrapper(target):
-		document_object_from_another(target, original)
-		return target
-	
-	return wrapper
+	target.__doc__ = original.__doc__
 
 
 def append_doctring_from_another(target, original):
@@ -75,43 +78,22 @@ def append_doctring_from_another(target, original):
 	:type original: any
 	"""
 
-	split_target_doc = target.__doc__.split("\n")
-	deindented_target_doc = [line.lstrip("\t ") for line in split_target_doc]
-	
-	split_original_doc = original.__doc__.split("\n")
-	deindented_original_doc = [line.lstrip("\t ") for line in split_original_doc]
+	deindented_target_doc = deindent_string(target.__doc__)
+	deindented_original_doc = deindent_string(original.__doc__)
 
-	target.__doc__ = f"\n".join(deindented_target_doc + deindented_original_doc)
-
-
-def append_docstring_from(original):
-	"""
-	Appends the docstring from the `original` function to the `target` function.
-
-	This may be useful for subclasses or wrappers that use the same arguments.
-
-	Any indentation in either docstring is removed to
-	ensure consistent indentation between the two docstrings.
-	Bear this in mind if additional indentation is used in the docstring.
-	"""
-	
-	def wrapper(target):
-		append_doctring_from_another(target, original)
-		return target
-	
-	return wrapper
+	target.__doc__ = deindented_target_doc + "\n" + deindented_original_doc
 
 
 def make_sphinx_links(input_string, builtins_list=None):
 	"""
 	Make proper sphinx links out of double-backticked strings in docstring.
 
 	i.e. \`\`str\`\` becomes \:class\:\`~python:str\`
-	
-	
+
+
 	Make sure to have `'python': ('https://docs.python.org/3/', None),` in the
 	`intersphinx_mapping` dict of your conf.py for sphinx.
-	
+
 	:param input_string: The string to process
 	:type input_string: str
 	:param builtins_list: A list of builtins to make links for
@@ -132,6 +114,39 @@ def make_sphinx_links(input_string, builtins_list=None):
 	return working_string
 
 
+# Decorators that call the above functions
+def is_documented_by(original):
+	"""
+	Sets the docstring of the `target` function to that of the `original` function.
+
+	This may be useful for subclasses or wrappers that use the same arguments.
+	"""
+	
+	def wrapper(target):
+		document_object_from_another(target, original)
+		return target
+	
+	return wrapper
+
+
+def append_docstring_from(original):
+	"""
+	Appends the docstring from the `original` function to the `target` function.
+
+	This may be useful for subclasses or wrappers that use the same arguments.
+
+	Any indentation in either docstring is removed to
+	ensure consistent indentation between the two docstrings.
+	Bear this in mind if additional indentation is used in the docstring.
+	"""
+	
+	def wrapper(target):
+		append_doctring_from_another(target, original)
+		return target
+	
+	return wrapper
+
+
 def sphinxify_docstring():
 	"""
 	Make proper sphinx links out of double-backticked strings in docstring.

domdf_python_tools/paths.py

@@ -85,27 +85,34 @@ def maybe_make(directory):
 	Makes a directory only if it doesn't already exist
 
 	:param directory: Directory to create
-	:type directory: str
+	:type directory: str or pathlib.Path
 	
 	"""
 
-	if not os.path.exists(directory):
-		os.makedirs(directory)
+	if not isinstance(directory, pathlib.Path):
+		directory = pathlib.Path(directory)
+	
+	if not directory.exists():
+		directory.mkdir()
 
 
 def parent_path(path):
 	"""
 	Returns the path of the parent directory for the given file or directory
 	
 	:param path: Path to find the parent for
-	:type path: str
+	:type path: str or pathlib.Path
 	
-	:return:
+	:return: The parent directory
+	:rtype: pathlib.Path
 	"""
 
-	return os.path.abspath(os.path.join(path,os.pardir))
-
+	if not isinstance(path, pathlib.Path):
+		path = pathlib.Path(path)
+	
+	return path.parent
 
+	
 def relpath(path, relative_to=None):
 	"""
 	Returns the path for the given file or directory relative to the given directory

domdf_python_tools/utils.py

@@ -148,7 +148,7 @@ def list2str(the_list, sep=","):
 	return sep.join([str(x) for x in the_list])
 
 
-def splitLen(string, n):
+def split_len(string, n):
 	"""
 	Split a string every x characters
 	
@@ -161,9 +161,13 @@ def splitLen(string, n):
 	return [string[i:i + n] for i in range(0, len(string), n)]
 
 
+splitLen = split_len
+
+
 def permutations(data, n=2):
 	"""
-	Return permutations containing `n` items from `data` without any reverse duplicates
+	Return permutations containing `n` items from `data` without any reverse duplicates.
+	If ``n`` is equal to or greater than the length of the data an empty list of returned
 	
 	:type data: list or string
 	:type n: int
@@ -172,6 +176,10 @@ def permutations(data, n=2):
 	"""
 
 	import itertools
+	
+	if n == 0:
+		raise ValueError("`n` cannot be 0")
+	
 	perms = []
 	for i in itertools.permutations(data, n):
 		"""from https://stackoverflow.com/questions/10201977/how-to-reverse-tuples-in-python"""