Added new, untested, dates module

Author: domdfcoding

__pkginfo__.py

@@ -1,4 +1,4 @@
-# Copyright © 2019 Dominic Davis-Foster <[email protected]>
+# Copyright © 2020 Dominic Davis-Foster <[email protected]>
 #
 #  This program is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -15,48 +15,43 @@
 
 # This script based on https://github.com/rocky/python-uncompyle6/blob/master/__pkginfo__.py
 
-copyright   = """
+import pathlib
+
+copyright = """
 2019 Dominic Davis-Foster <[email protected]>
 """
 
 VERSION = "0.1.21"
 
-modname            = "domdf_python_tools"
-py_modules		   = None
-entry_points	   = None
-
-license            = 'LGPL3'
-
-short_desc         = 'Helpful functions for Python'
-
-classifiers =  ['Development Status :: 4 - Beta',
-				'Intended Audience :: Developers',
-				"License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
-				'Operating System :: OS Independent',
-				'Programming Language :: Python',
-				'Programming Language :: Python :: 3.6',
-				'Programming Language :: Python :: 3.7',
-				'Programming Language :: Python :: 3.8',
-				'Topic :: Software Development :: Libraries :: Python Modules',
-				]
-
-author             = "Dominic Davis-Foster"
-author_email       = "[email protected]"
-github_username	   = "domdfcoding"
-web                = github_url = f"https://github.com/{github_username}/{modname}"
+modname = "domdf_python_tools"
+py_modules = None
+entry_points = None
 
-install_requires   = []
+license = 'LGPLv3+'
 
+short_desc = 'Helpful functions for Python'
 
-import os.path
-def get_srcdir():
-	filename = os.path.normcase(os.path.dirname(os.path.abspath(__file__)))
-	return os.path.realpath(filename)
+classifiers = [
+		'Development Status :: 4 - Beta',
+		'Intended Audience :: Developers',
+		"License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+		'Operating System :: OS Independent',
+		'Programming Language :: Python',
+		'Programming Language :: Python :: 3.6',
+		'Programming Language :: Python :: 3.7',
+		'Programming Language :: Python :: 3.8',
+		'Topic :: Software Development :: Libraries :: Python Modules',
+		]
 
-srcdir = get_srcdir()
+author = "Dominic Davis-Foster"
+author_email = "[email protected]"
+github_username = "domdfcoding"
+web = github_url = f"https://github.com/{github_username}/{modname}"
 
-def read(*rnames):
-	return open(os.path.join(srcdir, *rnames)).read()
+install_requires = []
 
 # Get info from files; set: long_description
-long_description   = ( read("README.rst") + '\n' )
+if pathlib.Path.cwd().name == "doc-source":
+	long_description = (pathlib.Path.cwd().parent / "README.rst").read_text() + '\n'
+else:
+	long_description = pathlib.Path("README.rst").read_text() + '\n'

doc-source/conf.py

@@ -32,12 +32,12 @@
 language = 'en'
 
 extensions = [
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinxcontrib.httpdomain',
-]
+		'sphinx.ext.intersphinx',
+		'sphinx.ext.autodoc',
+		'sphinx.ext.mathjax',
+		'sphinx.ext.viewcode',
+		'sphinxcontrib.httpdomain',
+		]
 
 templates_path = ['_templates']
 source_suffix = '.rst'
@@ -47,66 +47,67 @@
 suppress_warnings = ['image.nonlocal_uri']
 pygments_style = 'default'
 
-intersphinx_mapping = { # Is this where those mystery links are specified?
-    'rtd': ('https://docs.readthedocs.io/en/latest/', None),
-    'sphinx': ('http://www.sphinx-doc.org/en/stable/', None),
-}
+intersphinx_mapping = {
+		'rtd': ('https://docs.readthedocs.io/en/latest/', None),
+		'sphinx': ('http://www.sphinx-doc.org/en/stable/', None),
+		'python': ('https://docs.python.org/3/', None),
+		}
 
 html_theme = 'sphinx_rtd_theme'
 html_theme_options = {
-    'logo_only': False,  # True will show just the logo
-}
+		'logo_only': False,  # True will show just the logo
+		}
 html_theme_path = ["../.."]
-#html_logo = "logo/pyms.png"
-html_show_sourcelink = False    # True will show link to source
+# html_logo = "logo/pyms.png"
+html_show_sourcelink = False  # True will show link to source
 
 html_context = {
-    # Github Settings
-    "display_github": True, # Integrate GitHub
-    "github_user": "domdfcoding", # Username
-    "github_repo": "domdf_python_tools", # Repo name
-    "github_version": "master", # Version
-    "conf_py_path": "/", # Path in the checkout to the docs root
-}
+		# Github Settings
+		"display_github": True,  # Integrate GitHub
+		"github_user": "domdfcoding",  # Username
+		"github_repo": "domdf_python_tools",  # Repo name
+		"github_version": "master",  # Version
+		"conf_py_path": "/",  # Path in the checkout to the docs root
+		}
 
 htmlhelp_basename = slug
 
 latex_documents = [
-  ('index', '{0}.tex'.format(slug), project, author, 'manual'),
-]
+		('index', '{0}.tex'.format(slug), project, author, 'manual'),
+		]
 
 man_pages = [
-    ('index', slug, project, [author], 1)
-]
+		('index', slug, project, [author], 1)
+		]
 
 texinfo_documents = [
-  ('index', slug, project, author, slug, project, 'Miscellaneous'),
-]
+		('index', slug, project, author, slug, project, 'Miscellaneous'),
+		]
 
 
 # Extensions to theme docs
 def setup(app):
-    from sphinx.domains.python import PyField
-    from sphinx.util.docfields import Field
-
-    app.add_object_type(
-        'confval',
-        'confval',
-        objname='configuration value',
-        indextemplate='pair: %s; configuration value',
-        doc_field_types=[
-            PyField(
-                'type',
-                label=_('Type'),
-                has_arg=False,
-                names=('type',),
-                bodyrolename='class'
-            ),
-            Field(
-                'default',
-                label=_('Default'),
-                has_arg=False,
-                names=('default',),
-            ),
-        ]
-    )
+	from sphinx.domains.python import PyField
+	from sphinx.util.docfields import Field
+	
+	app.add_object_type(
+			'confval',
+			'confval',
+			objname='configuration value',
+			indextemplate='pair: %s; configuration value',
+			doc_field_types=[
+					PyField(
+							'type',
+							label=_('Type'),
+							has_arg=False,
+							names=('type',),
+							bodyrolename='class'
+							),
+					Field(
+							'default',
+							label=_('Default'),
+							has_arg=False,
+							names=('default',),
+							),
+					]
+			)

doc-source/docs.rst

@@ -9,6 +9,19 @@
     :private-members:
     :special-members:
 
+==================================
+:mod:`domdf_python_tools.dates`
+==================================
+
+.. warning:: This module has not been fully tested. Use with caution.
+
+.. note:: This module requires the `pytz <https://pypi.org/project/pytz/>`_ package to be installed.
+
+.. automodule:: domdf_python_tools.dates
+    :members:
+    :private-members:
+    :special-members:
+
 ==================================
 :mod:`domdf_python_tools.doctools`
 ==================================

domdf_python_tools/__init__.py

@@ -16,16 +16,14 @@
 #
 
 
-import sys
-
 from domdf_python_tools.utils import *
 from domdf_python_tools import paths, terminal, utils, doctools
 
-__all__ = ["paths", "terminal", "utils"]
+__all__ = ["paths", "terminal", "utils", "dates"]
 
 __author__ = "Dominic Davis-Foster"
 __copyright__ = "2014-2019 Dominic Davis-Foster"
 
-__license__ = "LGPL"
+__license__ = "LGPLv3+"
 __version__ = "0.1.21"
 __email__ = "[email protected]"

domdf_python_tools/dates.py

@@ -0,0 +1,103 @@
+#  !/usr/bin/env python
+#   -*- coding: utf-8 -*-
+#
+#  dates.py
+"""
+Utilities for working with dates and times
+"""
+#
+#  Copyright © 2020 Dominic Davis-Foster <[email protected]>
+#
+#  Parts of the docstrings based on the Python 3.8.2 Documentation
+#  Licensed under the Python Software Foundation License Version 2.
+#  Copyright © 2001-2020 Python Software Foundation. All rights reserved.
+#  Copyright © 2000 BeOpen.com . All rights reserved.
+#  Copyright © 1995-2000 Corporation for National Research Initiatives . All rights reserved.
+#  Copyright © 1991-1995 Stichting Mathematisch Centrum . All rights reserved.
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, write to the Free Software
+#  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#  MA 02110-1301, USA.
+#
+
+# stdlib
+import datetime
+
+# 3rd party
+try:
+	import pytz
+	
+	def current_tzinfo():
+		"""
+		Returns a tzinfo object for the current timezone
+		
+		:rtype: :class:`~python:datetime.datetime.tzinfo`
+		"""
+		
+		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.datetime.tzinfo`
+		
+		:return: Timestamp in UTC timezone
+		:rtype: float
+		"""
+		
+		return datetime.astimezone(current_tzinfo).replace(tzinfo=pytz.UTC).timestamp()
+	
+	
+	def utc_timestamp_to_datetime(utc_timestamp, output_tz=None):
+		"""
+		Convert UTC timestamp (seconds from UNIX epoch) to a :class:`datetime.datetime` object
+		
+		If ``output_tz`` is None the timestamp is converted to the platform’s local date and time,
+		and the local timezone is inferred and set for the object.
+	
+		If ``output_tz`` is not None, it must be an instance of a :class:`~python:datetime.datetime.tzinfo` subclass,
+		and the timestamp is converted to tz’s time zone.
+	
+		
+		:param utc_timestamp: The timestamp to convert to a datetime object
+		:type utc_timestamp: float, int
+		:param output_tz: The timezone to output the datetime object for.
+			If None it will be inferred.
+		:type output_tz: :class:`~python:datetime.datetime.tzinfo`
+		
+		:return: The timestamp as a datetime object.
+		:rtype: :class:`datetime.datetime`
+		
+		:raises: :class:`~python:OverflowError` if the timestamp is out of the range
+			of values supported by the platform C localtime() or gmtime() functions,
+			and OSError on localtime() or gmtime() failure. It’s common for this to
+			be restricted to years in 1970 through 2038.
+		"""
+		
+		new_datetime = datetime.datetime.fromtimestamp(utc_timestamp, output_tz)
+		
+		if output_tz is None:
+			return new_datetime.astimezone()
+		else:
+			return new_datetime
+
+except ImportError:
+	import warnings
+	warnings.warn("'domdf_python_tools.dates' requires pytz (https://pypi.org/project/pytz/), but it is not installed.")