Deploying to gh-pages from @ 71bf192 🚀

Author: mattwang44

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: cb10d30bafb08cf1c216562b1e263843
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_downloads/6dc1f3f4f0e6ca13cb42ddf4d6cbc8af/tzinfo_examples.py

@@ -0,0 +1,175 @@
+from datetime import tzinfo, timedelta, datetime
+
+ZERO = timedelta(0)
+HOUR = timedelta(hours=1)
+SECOND = timedelta(seconds=1)
+
+# A class capturing the platform's idea of local time.
+# (May result in wrong values on historical times in
+#  timezones where UTC offset and/or the DST rules had
+#  changed in the past.)
+import time as _time
+
+STDOFFSET = timedelta(seconds = -_time.timezone)
+if _time.daylight:
+    DSTOFFSET = timedelta(seconds = -_time.altzone)
+else:
+    DSTOFFSET = STDOFFSET
+
+DSTDIFF = DSTOFFSET - STDOFFSET
+
+class LocalTimezone(tzinfo):
+
+    def fromutc(self, dt):
+        assert dt.tzinfo is self
+        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
+        args = _time.localtime(stamp)[:6]
+        dst_diff = DSTDIFF // SECOND
+        # Detect fold
+        fold = (args == _time.localtime(stamp - dst_diff))
+        return datetime(*args, microsecond=dt.microsecond,
+                        tzinfo=self, fold=fold)
+
+    def utcoffset(self, dt):
+        if self._isdst(dt):
+            return DSTOFFSET
+        else:
+            return STDOFFSET
+
+    def dst(self, dt):
+        if self._isdst(dt):
+            return DSTDIFF
+        else:
+            return ZERO
+
+    def tzname(self, dt):
+        return _time.tzname[self._isdst(dt)]
+
+    def _isdst(self, dt):
+        tt = (dt.year, dt.month, dt.day,
+              dt.hour, dt.minute, dt.second,
+              dt.weekday(), 0, 0)
+        stamp = _time.mktime(tt)
+        tt = _time.localtime(stamp)
+        return tt.tm_isdst > 0
+
+Local = LocalTimezone()
+
+
+# A complete implementation of current DST rules for major US time zones.
+
+def first_sunday_on_or_after(dt):
+    days_to_go = 6 - dt.weekday()
+    if days_to_go:
+        dt += timedelta(days_to_go)
+    return dt
+
+
+# US DST Rules
+#
+# This is a simplified (i.e., wrong for a few cases) set of rules for US
+# DST start and end times. For a complete and up-to-date set of DST rules
+# and timezone definitions, visit the Olson Database (or try pytz):
+# http://www.twinsun.com/tz/tz-link.htm
+# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
+#
+# In the US, since 2007, DST starts at 2am (standard time) on the second
+# Sunday in March, which is the first Sunday on or after Mar 8.
+DSTSTART_2007 = datetime(1, 3, 8, 2)
+# and ends at 2am (DST time) on the first Sunday of Nov.
+DSTEND_2007 = datetime(1, 11, 1, 2)
+# From 1987 to 2006, DST used to start at 2am (standard time) on the first
+# Sunday in April and to end at 2am (DST time) on the last
+# Sunday of October, which is the first Sunday on or after Oct 25.
+DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
+DSTEND_1987_2006 = datetime(1, 10, 25, 2)
+# From 1967 to 1986, DST used to start at 2am (standard time) on the last
+# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
+# on the last Sunday of October, which is the first Sunday
+# on or after Oct 25.
+DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
+DSTEND_1967_1986 = DSTEND_1987_2006
+
+def us_dst_range(year):
+    # Find start and end times for US DST. For years before 1967, return
+    # start = end for no DST.
+    if 2006 < year:
+        dststart, dstend = DSTSTART_2007, DSTEND_2007
+    elif 1986 < year < 2007:
+        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
+    elif 1966 < year < 1987:
+        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
+    else:
+        return (datetime(year, 1, 1), ) * 2
+
+    start = first_sunday_on_or_after(dststart.replace(year=year))
+    end = first_sunday_on_or_after(dstend.replace(year=year))
+    return start, end
+
+
+class USTimeZone(tzinfo):
+
+    def __init__(self, hours, reprname, stdname, dstname):
+        self.stdoffset = timedelta(hours=hours)
+        self.reprname = reprname
+        self.stdname = stdname
+        self.dstname = dstname
+
+    def __repr__(self):
+        return self.reprname
+
+    def tzname(self, dt):
+        if self.dst(dt):
+            return self.dstname
+        else:
+            return self.stdname
+
+    def utcoffset(self, dt):
+        return self.stdoffset + self.dst(dt)
+
+    def dst(self, dt):
+        if dt is None or dt.tzinfo is None:
+            # An exception may be sensible here, in one or both cases.
+            # It depends on how you want to treat them.  The default
+            # fromutc() implementation (called by the default astimezone()
+            # implementation) passes a datetime with dt.tzinfo is self.
+            return ZERO
+        assert dt.tzinfo is self
+        start, end = us_dst_range(dt.year)
+        # Can't compare naive to aware objects, so strip the timezone from
+        # dt first.
+        dt = dt.replace(tzinfo=None)
+        if start + HOUR <= dt < end - HOUR:
+            # DST is in effect.
+            return HOUR
+        if end - HOUR <= dt < end:
+            # Fold (an ambiguous hour): use dt.fold to disambiguate.
+            return ZERO if dt.fold else HOUR
+        if start <= dt < start + HOUR:
+            # Gap (a non-existent hour): reverse the fold rule.
+            return HOUR if dt.fold else ZERO
+        # DST is off.
+        return ZERO
+
+    def fromutc(self, dt):
+        assert dt.tzinfo is self
+        start, end = us_dst_range(dt.year)
+        start = start.replace(tzinfo=self)
+        end = end.replace(tzinfo=self)
+        std_time = dt + self.stdoffset
+        dst_time = std_time + HOUR
+        if end <= dst_time < end + HOUR:
+            # Repeated hour
+            return std_time.replace(fold=1)
+        if std_time < start or dst_time >= end:
+            # Standard time
+            return std_time
+        if start <= std_time < end - HOUR:
+            # Daylight saving time
+            return dst_time
+
+
+Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
+Central  = USTimeZone(-6, "Central",  "CST", "CDT")
+Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
+Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")

_images/hashlib-blake2-tree.png

@@ -0,0 +1,38 @@
+=====================
+About these documents
+=====================
+
+
+These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
+document processor specifically written for the Python documentation.
+
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
+.. _Sphinx: https://www.sphinx-doc.org/
+
+.. In the online version of these documents, you can submit comments and suggest
+   changes directly on the documentation pages.
+
+Development of the documentation and its toolchain is an entirely volunteer
+effort, just like Python itself.  If you want to contribute, please take a
+look at the :ref:`reporting-bugs` page for information on how to do so.  New
+volunteers are always welcome!
+
+Many thanks go to:
+
+* Fred L. Drake, Jr., the creator of the original Python documentation toolset
+  and writer of much of the content;
+* the `Docutils <https://docutils.sourceforge.io/>`_ project for creating
+  reStructuredText and the Docutils suite;
+* Fredrik Lundh for his Alternative Python Reference project from which Sphinx
+  got many good ideas.
+
+
+Contributors to the Python Documentation
+----------------------------------------
+
+Many people have contributed to the Python language, the Python standard
+library, and the Python documentation.  See :source:`Misc/ACKS` in the Python
+source distribution for a partial list of contributors.
+
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!

_images/logging_flow.png

@@ -0,0 +1,105 @@
+.. _reporting-bugs:
+
+*****************
+Dealing with Bugs
+*****************
+
+Python is a mature programming language which has established a reputation for
+stability.  In order to maintain this reputation, the developers would like to
+know of any deficiencies you find in Python.
+
+It can be sometimes faster to fix bugs yourself and contribute patches to
+Python as it streamlines the process and involves less people. Learn how to
+:ref:`contribute <contributing-to-python>`.
+
+Documentation bugs
+==================
+
+If you find a bug in this documentation or would like to propose an improvement,
+please submit a bug report on the :ref:`tracker <using-the-tracker>`.  If you
+have a suggestion on how to fix it, include that as well.
+
+If you're short on time, you can also email documentation bug reports to
+[email protected] (behavioral bugs can be sent to [email protected]).
+'docs@' is a mailing list run by volunteers; your request will be noticed,
+though it may take a while to be processed.
+
+.. seealso::
+
+   `Documentation bugs`_
+      A list of documentation bugs that have been submitted to the Python issue tracker.
+
+   `Issue Tracking <https://devguide.python.org/tracker/>`_
+      Overview of the process involved in reporting an improvement on the tracker.
+
+   `Helping with Documentation <https://devguide.python.org/docquality/#helping-with-documentation>`_
+      Comprehensive guide for individuals that are interested in contributing to Python documentation.
+
+   `Documentation Translations <https://devguide.python.org/documenting/#translating>`_
+      A list of GitHub pages for documentation translation and their primary contacts.
+
+
+.. _using-the-tracker:
+
+Using the Python issue tracker
+==============================
+
+Issue reports for Python itself should be submitted via the GitHub issues
+tracker (https://github.com/python/cpython/issues).
+The GitHub issues tracker offers a web form which allows pertinent information
+to be entered and submitted to the developers.
+
+The first step in filing a report is to determine whether the problem has
+already been reported.  The advantage in doing so, aside from saving the
+developers' time, is that you learn what has been done to fix it; it may be that
+the problem has already been fixed for the next release, or additional
+information is needed (in which case you are welcome to provide it if you can!).
+To do this, search the tracker using the search box at the top of the page.
+
+If the problem you're reporting is not already in the list, log in to GitHub.
+If you don't already have a GitHub account, create a new account using the
+"Sign up" link.
+It is not possible to submit a bug report anonymously.
+
+Being now logged in, you can submit an issue.
+Click on the "New issue" button in the top bar to report a new issue.
+
+The submission form has two fields, "Title" and "Comment".
+
+For the "Title" field, enter a *very* short description of the problem;
+less than ten words is good.
+
+In the "Comment" field, describe the problem in detail, including what you
+expected to happen and what did happen.  Be sure to include whether any
+extension modules were involved, and what hardware and software platform you
+were using (including version information as appropriate).
+
+Each issue report will be reviewed by a developer who will determine what needs to
+be done to correct the problem. You will receive an update each time an action is
+taken on the issue.
+
+
+.. seealso::
+
+   `How to Report Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
+      Article which goes into some detail about how to create a useful bug report.
+      This describes what kind of information is useful and why it is useful.
+
+   `Bug Writing Guidelines <https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html>`_
+      Information about writing a good bug report.  Some of this is specific to the
+      Mozilla project, but describes general good practices.
+
+.. _contributing-to-python:
+
+Getting started contributing to Python yourself
+===============================================
+
+Beyond just reporting bugs that you find, you are also welcome to submit
+patches to fix them.  You can find more information on how to get started
+patching Python in the `Python Developer's Guide`_.  If you have questions,
+the `core-mentorship mailing list`_ is a friendly place to get answers to
+any and all questions pertaining to the process of fixing issues in Python.
+
+.. _Documentation bugs: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs
+.. _Python Developer's Guide: https://devguide.python.org/
+.. _core-mentorship mailing list: https://mail.python.org/mailman3/lists/core-mentorship.python.org/

_images/pathlib-inheritance.png

@@ -0,0 +1,27 @@
+.. highlight:: c
+
+.. _abstract:
+
+**********************
+Abstract Objects Layer
+**********************
+
+The functions in this chapter interact with Python objects regardless of their
+type, or with wide classes of object types (e.g. all numerical types, or all
+sequence types).  When used on object types for which they do not apply, they
+will raise a Python exception.
+
+It is not possible to use these functions on objects that are not properly
+initialized, such as a list object that has been created by :c:func:`PyList_New`,
+but whose items have not been set to some non-\ ``NULL`` value yet.
+
+.. toctree::
+
+   object.rst
+   call.rst
+   number.rst
+   sequence.rst
+   mapping.rst
+   iter.rst
+   buffer.rst
+   objbuffer.rst