Add files using upload-large-folder tool

sentiment-bert-model/model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d3a56cbfa62fb1546a0efc5c4204eaca9c45d3d1eacf4ac30c1d54c59df17d97
+size 437958648

venv/Lib/site-packages/arrow-1.3.0.dist-info/INSTALLER

@@ -0,0 +1 @@
+pip

venv/Lib/site-packages/arrow-1.3.0.dist-info/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023 Chris Smith
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

venv/Lib/site-packages/arrow-1.3.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.1
+Name: arrow
+Version: 1.3.0
+Summary: Better dates & times for Python
+Keywords: arrow,date,time,datetime,timestamp,timezone,humanize
+Author-email: Chris Smith <[email protected]>
+Requires-Python: >=3.8
+Description-Content-Type: text/x-rst
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Dist: python-dateutil>=2.7.0
+Requires-Dist: types-python-dateutil>=2.8.10
+Requires-Dist: doc8 ; extra == "doc"
+Requires-Dist: sphinx>=7.0.0 ; extra == "doc"
+Requires-Dist: sphinx-autobuild ; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints ; extra == "doc"
+Requires-Dist: sphinx_rtd_theme>=1.3.0 ; extra == "doc"
+Requires-Dist: dateparser==1.* ; extra == "test"
+Requires-Dist: pre-commit ; extra == "test"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: pytest-cov ; extra == "test"
+Requires-Dist: pytest-mock ; extra == "test"
+Requires-Dist: pytz==2021.1 ; extra == "test"
+Requires-Dist: simplejson==3.* ; extra == "test"
+Project-URL: Documentation, https://arrow.readthedocs.io
+Project-URL: Issues, https://github.com/arrow-py/arrow/issues
+Project-URL: Source, https://github.com/arrow-py/arrow
+Provides-Extra: doc
+Provides-Extra: test
+
+Arrow: Better dates & times for Python
+======================================
+
+.. start-inclusion-marker-do-not-remove
+
+.. image:: https://github.com/arrow-py/arrow/workflows/tests/badge.svg?branch=master
+   :alt: Build Status
+   :target: https://github.com/arrow-py/arrow/actions?query=workflow%3Atests+branch%3Amaster
+
+.. image:: https://codecov.io/gh/arrow-py/arrow/branch/master/graph/badge.svg
+   :alt: Coverage
+   :target: https://codecov.io/gh/arrow-py/arrow
+
+.. image:: https://img.shields.io/pypi/v/arrow.svg
+   :alt: PyPI Version
+   :target: https://pypi.python.org/pypi/arrow
+
+.. image:: https://img.shields.io/pypi/pyversions/arrow.svg
+   :alt: Supported Python Versions
+   :target: https://pypi.python.org/pypi/arrow
+
+.. image:: https://img.shields.io/pypi/l/arrow.svg
+   :alt: License
+   :target: https://pypi.python.org/pypi/arrow
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :alt: Code Style: Black
+   :target: https://github.com/psf/black
+
+
+**Arrow** is a Python library that offers a sensible and human-friendly approach to creating, manipulating, formatting and converting dates, times and timestamps. It implements and updates the datetime type, plugging gaps in functionality and providing an intelligent module API that supports many common creation scenarios. Simply put, it helps you work with dates and times with fewer imports and a lot less code.
+
+Arrow is named after the `arrow of time <https://en.wikipedia.org/wiki/Arrow_of_time>`_ and is heavily inspired by `moment.js <https://github.com/moment/moment>`_ and `requests <https://github.com/psf/requests>`_.
+
+Why use Arrow over built-in modules?
+------------------------------------
+
+Python's standard library and some other low-level modules have near-complete date, time and timezone functionality, but don't work very well from a usability perspective:
+
+- Too many modules: datetime, time, calendar, dateutil, pytz and more
+- Too many types: date, time, datetime, tzinfo, timedelta, relativedelta, etc.
+- Timezones and timestamp conversions are verbose and unpleasant
+- Timezone naivety is the norm
+- Gaps in functionality: ISO 8601 parsing, timespans, humanization
+
+Features
+--------
+
+- Fully-implemented, drop-in replacement for datetime
+- Support for Python 3.6+
+- Timezone-aware and UTC by default
+- Super-simple creation options for many common input scenarios
+- ``shift`` method with support for relative offsets, including weeks
+- Format and parse strings automatically
+- Wide support for the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ standard
+- Timezone conversion
+- Support for ``dateutil``, ``pytz``, and ``ZoneInfo`` tzinfo objects
+- Generates time spans, ranges, floors and ceilings for time frames ranging from microsecond to year
+- Humanize dates and times with a growing list of contributed locales
+- Extensible for your own Arrow-derived types
+- Full support for PEP 484-style type hints
+
+Quick Start
+-----------
+
+Installation
+~~~~~~~~~~~~
+
+To install Arrow, use `pip <https://pip.pypa.io/en/stable/quickstart/>`_ or `pipenv <https://docs.pipenv.org>`_:
+
+.. code-block:: console
+
+    $ pip install -U arrow
+
+Example Usage
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    >>> import arrow
+    >>> arrow.get('2013-05-11T21:23:58.970460+07:00')
+    <Arrow [2013-05-11T21:23:58.970460+07:00]>
+
+    >>> utc = arrow.utcnow()
+    >>> utc
+    <Arrow [2013-05-11T21:23:58.970460+00:00]>
+
+    >>> utc = utc.shift(hours=-1)
+    >>> utc
+    <Arrow [2013-05-11T20:23:58.970460+00:00]>
+
+    >>> local = utc.to('US/Pacific')
+    >>> local
+    <Arrow [2013-05-11T13:23:58.970460-07:00]>
+
+    >>> local.timestamp()
+    1368303838.970460
+
+    >>> local.format()
+    '2013-05-11 13:23:58 -07:00'
+
+    >>> local.format('YYYY-MM-DD HH:mm:ss ZZ')
+    '2013-05-11 13:23:58 -07:00'
+
+    >>> local.humanize()
+    'an hour ago'
+
+    >>> local.humanize(locale='ko-kr')
+    '한시간 전'
+
+.. end-inclusion-marker-do-not-remove
+
+Documentation
+-------------
+
+For full documentation, please visit `arrow.readthedocs.io <https://arrow.readthedocs.io>`_.
+
+Contributing
+------------
+
+Contributions are welcome for both code and localizations (adding and updating locales). Begin by gaining familiarity with the Arrow library and its features. Then, jump into contributing:
+
+#. Find an issue or feature to tackle on the `issue tracker <https://github.com/arrow-py/arrow/issues>`_. Issues marked with the `"good first issue" label <https://github.com/arrow-py/arrow/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_ may be a great place to start!
+#. Fork `this repository <https://github.com/arrow-py/arrow>`_ on GitHub and begin making changes in a branch.
+#. Add a few tests to ensure that the bug was fixed or the feature works as expected.
+#. Run the entire test suite and linting checks by running one of the following commands: ``tox && tox -e lint,docs`` (if you have `tox <https://tox.readthedocs.io>`_ installed) **OR** ``make build39 && make test && make lint`` (if you do not have Python 3.9 installed, replace ``build39`` with the latest Python version on your system).
+#. Submit a pull request and await feedback 😃.
+
+If you have any questions along the way, feel free to ask them `here <https://github.com/arrow-py/arrow/discussions>`_.
+
+Support Arrow
+-------------
+
+`Open Collective <https://opencollective.com/>`_ is an online funding platform that provides tools to raise money and share your finances with full transparency. It is the platform of choice for individuals and companies to make one-time or recurring donations directly to the project. If you are interested in making a financial contribution, please visit the `Arrow collective <https://opencollective.com/arrow>`_.
+

venv/Lib/site-packages/arrow-1.3.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+arrow-1.3.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+arrow-1.3.0.dist-info/LICENSE,sha256=tIH4cpbLCr2xP9jLuUsUwyi-iA7J5oVHphuE2s_9Bno,11341
+arrow-1.3.0.dist-info/METADATA,sha256=P7gh6Gt6pIqBLBP577OoTZWFhRmAOpMyiwpuNEeklac,7534
+arrow-1.3.0.dist-info/RECORD,,
+arrow-1.3.0.dist-info/WHEEL,sha256=EZbGkh7Ie4PoZfRQ8I0ZuP9VklN_TvcZ6DSE5Uar4z4,81
+arrow/__init__.py,sha256=HxsSJGl56GoeHB__No-kdGmC_Wes_Ttf0ohOy7OoFig,872
+arrow/__pycache__/__init__.cpython-312.pyc,,
+arrow/__pycache__/_version.cpython-312.pyc,,
+arrow/__pycache__/api.cpython-312.pyc,,
+arrow/__pycache__/arrow.cpython-312.pyc,,
+arrow/__pycache__/constants.cpython-312.pyc,,
+arrow/__pycache__/factory.cpython-312.pyc,,
+arrow/__pycache__/formatter.cpython-312.pyc,,
+arrow/__pycache__/locales.cpython-312.pyc,,
+arrow/__pycache__/parser.cpython-312.pyc,,
+arrow/__pycache__/util.cpython-312.pyc,,
+arrow/_version.py,sha256=F5mW07pSyGrqDNY2Ehr-UpDzpBtN-FsYU0QGZWf6PJE,22
+arrow/api.py,sha256=6tdqrG0NjrKO22_eWHU4a5xerfR6IrZPY-yynGpnvTM,2755
+arrow/arrow.py,sha256=m9XvNnpQ1aTHZWXPud3W2-QMfilgWXnUCnuZInwf27g,63517
+arrow/constants.py,sha256=y3scgWgxiFuQg4DeFlhmexy1BA7K8LFNZyqK-VWPQJs,3238
+arrow/factory.py,sha256=qiDSokfcVWJhiJbIkOcU1Ohh4N0PdKxghsJzBnI8AUo,11432
+arrow/formatter.py,sha256=0D0-AjBZwuay9312KvY0UnaVBfAZj-vEIqWcG0_3ZDQ,5267
+arrow/locales.py,sha256=6g5xHq5UkIAZPF8N2PvzN_xoUvsfNcPhNfJw0TUi8tw,156894
+arrow/parser.py,sha256=FO6NWpzjvZcsMhIck6pd7hKe1ijlKUZE9l_OFlyskyw,25790
+arrow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arrow/util.py,sha256=xnDevqRyNeYWbl3x-n_Tyo4cOgHcdgbxFECFsJ1XoEc,3679

venv/Lib/site-packages/arrow-1.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any

venv/Lib/site-packages/arrow/__init__.py

@@ -0,0 +1,39 @@
+from ._version import __version__
+from .api import get, now, utcnow
+from .arrow import Arrow
+from .factory import ArrowFactory
+from .formatter import (
+    FORMAT_ATOM,
+    FORMAT_COOKIE,
+    FORMAT_RFC822,
+    FORMAT_RFC850,
+    FORMAT_RFC1036,
+    FORMAT_RFC1123,
+    FORMAT_RFC2822,
+    FORMAT_RFC3339,
+    FORMAT_RSS,
+    FORMAT_W3C,
+)
+from .parser import ParserError
+
+# https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-no-implicit-reexport
+# Mypy with --strict or --no-implicit-reexport requires an explicit reexport.
+__all__ = [
+    "__version__",
+    "get",
+    "now",
+    "utcnow",
+    "Arrow",
+    "ArrowFactory",
+    "FORMAT_ATOM",
+    "FORMAT_COOKIE",
+    "FORMAT_RFC822",
+    "FORMAT_RFC850",
+    "FORMAT_RFC1036",
+    "FORMAT_RFC1123",
+    "FORMAT_RFC2822",
+    "FORMAT_RFC3339",
+    "FORMAT_RSS",
+    "FORMAT_W3C",
+    "ParserError",
+]

venv/Lib/site-packages/arrow/_version.py

@@ -0,0 +1 @@
+__version__ = "1.3.0"

venv/Lib/site-packages/arrow/arrow.py

@@ -0,0 +1,1869 @@
+"""
+Provides the :class:`Arrow <arrow.arrow.Arrow>` class, an enhanced ``datetime``
+replacement.
+
+"""
+
+
+import calendar
+import re
+import sys
+from datetime import date
+from datetime import datetime as dt_datetime
+from datetime import time as dt_time
+from datetime import timedelta
+from datetime import tzinfo as dt_tzinfo
+from math import trunc
+from time import struct_time
+from typing import (
+    Any,
+    ClassVar,
+    Generator,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Tuple,
+    Union,
+    cast,
+    overload,
+)
+
+from dateutil import tz as dateutil_tz
+from dateutil.relativedelta import relativedelta
+
+from arrow import formatter, locales, parser, util
+from arrow.constants import DEFAULT_LOCALE, DEHUMANIZE_LOCALES
+from arrow.locales import TimeFrameLiteral
+
+if sys.version_info < (3, 8):  # pragma: no cover
+    from typing_extensions import Final, Literal
+else:
+    from typing import Final, Literal  # pragma: no cover
+
+
+TZ_EXPR = Union[dt_tzinfo, str]
+
+_T_FRAMES = Literal[
+    "year",
+    "years",
+    "month",
+    "months",
+    "day",
+    "days",
+    "hour",
+    "hours",
+    "minute",
+    "minutes",
+    "second",
+    "seconds",
+    "microsecond",
+    "microseconds",
+    "week",
+    "weeks",
+    "quarter",
+    "quarters",
+]
+
+_BOUNDS = Literal["[)", "()", "(]", "[]"]
+
+_GRANULARITY = Literal[
+    "auto",
+    "second",
+    "minute",
+    "hour",
+    "day",
+    "week",
+    "month",
+    "quarter",
+    "year",
+]
+
+
+class Arrow:
+    """An :class:`Arrow <arrow.arrow.Arrow>` object.
+
+    Implements the ``datetime`` interface, behaving as an aware ``datetime`` while implementing
+    additional functionality.
+
+    :param year: the calendar year.
+    :param month: the calendar month.
+    :param day: the calendar day.
+    :param hour: (optional) the hour. Defaults to 0.
+    :param minute: (optional) the minute, Defaults to 0.
+    :param second: (optional) the second, Defaults to 0.
+    :param microsecond: (optional) the microsecond. Defaults to 0.
+    :param tzinfo: (optional) A timezone expression.  Defaults to UTC.
+    :param fold: (optional) 0 or 1, used to disambiguate repeated wall times. Defaults to 0.
+
+    .. _tz-expr:
+
+    Recognized timezone expressions:
+
+        - A ``tzinfo`` object.
+        - A ``str`` describing a timezone, similar to 'US/Pacific', or 'Europe/Berlin'.
+        - A ``str`` in ISO 8601 style, as in '+07:00'.
+        - A ``str``, one of the following:  'local', 'utc', 'UTC'.
+
+    Usage::
+
+        >>> import arrow
+        >>> arrow.Arrow(2013, 5, 5, 12, 30, 45)
+        <Arrow [2013-05-05T12:30:45+00:00]>
+
+    """
+
+    resolution: ClassVar[timedelta] = dt_datetime.resolution
+    min: ClassVar["Arrow"]
+    max: ClassVar["Arrow"]
+
+    _ATTRS: Final[List[str]] = [
+        "year",
+        "month",
+        "day",
+        "hour",
+        "minute",
+        "second",
+        "microsecond",
+    ]
+    _ATTRS_PLURAL: Final[List[str]] = [f"{a}s" for a in _ATTRS]
+    _MONTHS_PER_QUARTER: Final[int] = 3
+    _SECS_PER_MINUTE: Final[int] = 60
+    _SECS_PER_HOUR: Final[int] = 60 * 60
+    _SECS_PER_DAY: Final[int] = 60 * 60 * 24
+    _SECS_PER_WEEK: Final[int] = 60 * 60 * 24 * 7
+    _SECS_PER_MONTH: Final[float] = 60 * 60 * 24 * 30.5
+    _SECS_PER_QUARTER: Final[float] = 60 * 60 * 24 * 30.5 * 3
+    _SECS_PER_YEAR: Final[int] = 60 * 60 * 24 * 365
+
+    _SECS_MAP: Final[Mapping[TimeFrameLiteral, float]] = {
+        "second": 1.0,
+        "minute": _SECS_PER_MINUTE,
+        "hour": _SECS_PER_HOUR,
+        "day": _SECS_PER_DAY,
+        "week": _SECS_PER_WEEK,
+        "month": _SECS_PER_MONTH,
+        "quarter": _SECS_PER_QUARTER,
+        "year": _SECS_PER_YEAR,
+    }
+
+    _datetime: dt_datetime
+
+    def __init__(
+        self,
+        year: int,
+        month: int,
+        day: int,
+        hour: int = 0,
+        minute: int = 0,
+        second: int = 0,
+        microsecond: int = 0,
+        tzinfo: Optional[TZ_EXPR] = None,
+        **kwargs: Any,
+    ) -> None:
+        if tzinfo is None:
+            tzinfo = dateutil_tz.tzutc()
+        # detect that tzinfo is a pytz object (issue #626)
+        elif (
+            isinstance(tzinfo, dt_tzinfo)
+            and hasattr(tzinfo, "localize")
+            and hasattr(tzinfo, "zone")
+            and tzinfo.zone
+        ):
+            tzinfo = parser.TzinfoParser.parse(tzinfo.zone)
+        elif isinstance(tzinfo, str):
+            tzinfo = parser.TzinfoParser.parse(tzinfo)
+
+        fold = kwargs.get("fold", 0)
+
+        self._datetime = dt_datetime(
+            year, month, day, hour, minute, second, microsecond, tzinfo, fold=fold
+        )
+
+    # factories: single object, both original and from datetime.
+
+    @classmethod
+    def now(cls, tzinfo: Optional[dt_tzinfo] = None) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object, representing "now" in the given
+        timezone.
+
+        :param tzinfo: (optional) a ``tzinfo`` object. Defaults to local time.
+
+        Usage::
+
+            >>> arrow.now('Asia/Baku')
+            <Arrow [2019-01-24T20:26:31.146412+04:00]>
+
+        """
+
+        if tzinfo is None:
+            tzinfo = dateutil_tz.tzlocal()
+
+        dt = dt_datetime.now(tzinfo)
+
+        return cls(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            dt.tzinfo,
+            fold=getattr(dt, "fold", 0),
+        )
+
+    @classmethod
+    def utcnow(cls) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object, representing "now" in UTC
+        time.
+
+        Usage::
+
+            >>> arrow.utcnow()
+            <Arrow [2019-01-24T16:31:40.651108+00:00]>
+
+        """
+
+        dt = dt_datetime.now(dateutil_tz.tzutc())
+
+        return cls(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            dt.tzinfo,
+            fold=getattr(dt, "fold", 0),
+        )
+
+    @classmethod
+    def fromtimestamp(
+        cls,
+        timestamp: Union[int, float, str],
+        tzinfo: Optional[TZ_EXPR] = None,
+    ) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object from a timestamp, converted to
+        the given timezone.
+
+        :param timestamp: an ``int`` or ``float`` timestamp, or a ``str`` that converts to either.
+        :param tzinfo: (optional) a ``tzinfo`` object.  Defaults to local time.
+
+        """
+
+        if tzinfo is None:
+            tzinfo = dateutil_tz.tzlocal()
+        elif isinstance(tzinfo, str):
+            tzinfo = parser.TzinfoParser.parse(tzinfo)
+
+        if not util.is_timestamp(timestamp):
+            raise ValueError(f"The provided timestamp {timestamp!r} is invalid.")
+
+        timestamp = util.normalize_timestamp(float(timestamp))
+        dt = dt_datetime.fromtimestamp(timestamp, tzinfo)
+
+        return cls(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            dt.tzinfo,
+            fold=getattr(dt, "fold", 0),
+        )
+
+    @classmethod
+    def utcfromtimestamp(cls, timestamp: Union[int, float, str]) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object from a timestamp, in UTC time.
+
+        :param timestamp: an ``int`` or ``float`` timestamp, or a ``str`` that converts to either.
+
+        """
+
+        if not util.is_timestamp(timestamp):
+            raise ValueError(f"The provided timestamp {timestamp!r} is invalid.")
+
+        timestamp = util.normalize_timestamp(float(timestamp))
+        dt = dt_datetime.utcfromtimestamp(timestamp)
+
+        return cls(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            dateutil_tz.tzutc(),
+            fold=getattr(dt, "fold", 0),
+        )
+
+    @classmethod
+    def fromdatetime(cls, dt: dt_datetime, tzinfo: Optional[TZ_EXPR] = None) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object from a ``datetime`` and
+        optional replacement timezone.
+
+        :param dt: the ``datetime``
+        :param tzinfo: (optional) A :ref:`timezone expression <tz-expr>`.  Defaults to ``dt``'s
+            timezone, or UTC if naive.
+
+        Usage::
+
+            >>> dt
+            datetime.datetime(2021, 4, 7, 13, 48, tzinfo=tzfile('/usr/share/zoneinfo/US/Pacific'))
+            >>> arrow.Arrow.fromdatetime(dt)
+            <Arrow [2021-04-07T13:48:00-07:00]>
+
+        """
+
+        if tzinfo is None:
+            if dt.tzinfo is None:
+                tzinfo = dateutil_tz.tzutc()
+            else:
+                tzinfo = dt.tzinfo
+
+        return cls(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            tzinfo,
+            fold=getattr(dt, "fold", 0),
+        )
+
+    @classmethod
+    def fromdate(cls, date: date, tzinfo: Optional[TZ_EXPR] = None) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object from a ``date`` and optional
+        replacement timezone.  All time values are set to 0.
+
+        :param date: the ``date``
+        :param tzinfo: (optional) A :ref:`timezone expression <tz-expr>`.  Defaults to UTC.
+
+        """
+
+        if tzinfo is None:
+            tzinfo = dateutil_tz.tzutc()
+
+        return cls(date.year, date.month, date.day, tzinfo=tzinfo)
+
+    @classmethod
+    def strptime(
+        cls, date_str: str, fmt: str, tzinfo: Optional[TZ_EXPR] = None
+    ) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object from a date string and format,
+        in the style of ``datetime.strptime``.  Optionally replaces the parsed timezone.
+
+        :param date_str: the date string.
+        :param fmt: the format string using datetime format codes.
+        :param tzinfo: (optional) A :ref:`timezone expression <tz-expr>`.  Defaults to the parsed
+            timezone if ``fmt`` contains a timezone directive, otherwise UTC.
+
+        Usage::
+
+            >>> arrow.Arrow.strptime('20-01-2019 15:49:10', '%d-%m-%Y %H:%M:%S')
+            <Arrow [2019-01-20T15:49:10+00:00]>
+
+        """
+
+        dt = dt_datetime.strptime(date_str, fmt)
+        if tzinfo is None:
+            tzinfo = dt.tzinfo
+
+        return cls(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            tzinfo,
+            fold=getattr(dt, "fold", 0),
+        )
+
+    @classmethod
+    def fromordinal(cls, ordinal: int) -> "Arrow":
+        """Constructs an :class:`Arrow <arrow.arrow.Arrow>` object corresponding
+            to the Gregorian Ordinal.
+
+        :param ordinal: an ``int`` corresponding to a Gregorian Ordinal.
+
+        Usage::
+
+            >>> arrow.fromordinal(737741)
+            <Arrow [2020-11-12T00:00:00+00:00]>
+
+        """
+
+        util.validate_ordinal(ordinal)
+        dt = dt_datetime.fromordinal(ordinal)
+        return cls(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            dt.tzinfo,
+            fold=getattr(dt, "fold", 0),
+        )
+
+    # factories: ranges and spans
+
+    @classmethod
+    def range(
+        cls,
+        frame: _T_FRAMES,
+        start: Union["Arrow", dt_datetime],
+        end: Union["Arrow", dt_datetime, None] = None,
+        tz: Optional[TZ_EXPR] = None,
+        limit: Optional[int] = None,
+    ) -> Generator["Arrow", None, None]:
+        """Returns an iterator of :class:`Arrow <arrow.arrow.Arrow>` objects, representing
+        points in time between two inputs.
+
+        :param frame: The timeframe.  Can be any ``datetime`` property (day, hour, minute...).
+        :param start: A datetime expression, the start of the range.
+        :param end: (optional) A datetime expression, the end of the range.
+        :param tz: (optional) A :ref:`timezone expression <tz-expr>`.  Defaults to
+            ``start``'s timezone, or UTC if ``start`` is naive.
+        :param limit: (optional) A maximum number of tuples to return.
+
+        **NOTE**: The ``end`` or ``limit`` must be provided.  Call with ``end`` alone to
+        return the entire range.  Call with ``limit`` alone to return a maximum # of results from
+        the start.  Call with both to cap a range at a maximum # of results.
+
+        **NOTE**: ``tz`` internally **replaces** the timezones of both ``start`` and ``end`` before
+        iterating.  As such, either call with naive objects and ``tz``, or aware objects from the
+        same timezone and no ``tz``.
+
+        Supported frame values: year, quarter, month, week, day, hour, minute, second, microsecond.
+
+        Recognized datetime expressions:
+
+            - An :class:`Arrow <arrow.arrow.Arrow>` object.
+            - A ``datetime`` object.
+
+        Usage::
+
+            >>> start = datetime(2013, 5, 5, 12, 30)
+            >>> end = datetime(2013, 5, 5, 17, 15)
+            >>> for r in arrow.Arrow.range('hour', start, end):
+            ...     print(repr(r))
+            ...
+            <Arrow [2013-05-05T12:30:00+00:00]>
+            <Arrow [2013-05-05T13:30:00+00:00]>
+            <Arrow [2013-05-05T14:30:00+00:00]>
+            <Arrow [2013-05-05T15:30:00+00:00]>
+            <Arrow [2013-05-05T16:30:00+00:00]>
+
+        **NOTE**: Unlike Python's ``range``, ``end`` *may* be included in the returned iterator::
+
+            >>> start = datetime(2013, 5, 5, 12, 30)
+            >>> end = datetime(2013, 5, 5, 13, 30)
+            >>> for r in arrow.Arrow.range('hour', start, end):
+            ...     print(repr(r))
+            ...
+            <Arrow [2013-05-05T12:30:00+00:00]>
+            <Arrow [2013-05-05T13:30:00+00:00]>
+
+        """
+
+        _, frame_relative, relative_steps = cls._get_frames(frame)
+
+        tzinfo = cls._get_tzinfo(start.tzinfo if tz is None else tz)
+
+        start = cls._get_datetime(start).replace(tzinfo=tzinfo)
+        end, limit = cls._get_iteration_params(end, limit)
+        end = cls._get_datetime(end).replace(tzinfo=tzinfo)
+
+        current = cls.fromdatetime(start)
+        original_day = start.day
+        day_is_clipped = False
+        i = 0
+
+        while current <= end and i < limit:
+            i += 1
+            yield current
+
+            values = [getattr(current, f) for f in cls._ATTRS]
+            current = cls(*values, tzinfo=tzinfo).shift(  # type: ignore[misc]
+                **{frame_relative: relative_steps}
+            )
+
+            if frame in ["month", "quarter", "year"] and current.day < original_day:
+                day_is_clipped = True
+
+            if day_is_clipped and not cls._is_last_day_of_month(current):
+                current = current.replace(day=original_day)
+
+    def span(
+        self,
+        frame: _T_FRAMES,
+        count: int = 1,
+        bounds: _BOUNDS = "[)",
+        exact: bool = False,
+        week_start: int = 1,
+    ) -> Tuple["Arrow", "Arrow"]:
+        """Returns a tuple of two new :class:`Arrow <arrow.arrow.Arrow>` objects, representing the timespan
+        of the :class:`Arrow <arrow.arrow.Arrow>` object in a given timeframe.
+
+        :param frame: the timeframe.  Can be any ``datetime`` property (day, hour, minute...).
+        :param count: (optional) the number of frames to span.
+        :param bounds: (optional) a ``str`` of either '()', '(]', '[)', or '[]' that specifies
+            whether to include or exclude the start and end values in the span. '(' excludes
+            the start, '[' includes the start, ')' excludes the end, and ']' includes the end.
+            If the bounds are not specified, the default bound '[)' is used.
+        :param exact: (optional) whether to have the start of the timespan begin exactly
+            at the time specified by ``start`` and the end of the timespan truncated
+            so as not to extend beyond ``end``.
+        :param week_start: (optional) only used in combination with the week timeframe. Follows isoweekday() where
+            Monday is 1 and Sunday is 7.
+
+        Supported frame values: year, quarter, month, week, day, hour, minute, second.
+
+        Usage::
+
+            >>> arrow.utcnow()
+            <Arrow [2013-05-09T03:32:36.186203+00:00]>
+
+            >>> arrow.utcnow().span('hour')
+            (<Arrow [2013-05-09T03:00:00+00:00]>, <Arrow [2013-05-09T03:59:59.999999+00:00]>)
+
+            >>> arrow.utcnow().span('day')
+            (<Arrow [2013-05-09T00:00:00+00:00]>, <Arrow [2013-05-09T23:59:59.999999+00:00]>)
+
+            >>> arrow.utcnow().span('day', count=2)
+            (<Arrow [2013-05-09T00:00:00+00:00]>, <Arrow [2013-05-10T23:59:59.999999+00:00]>)
+
+            >>> arrow.utcnow().span('day', bounds='[]')
+            (<Arrow [2013-05-09T00:00:00+00:00]>, <Arrow [2013-05-10T00:00:00+00:00]>)
+
+            >>> arrow.utcnow().span('week')
+            (<Arrow [2021-02-22T00:00:00+00:00]>, <Arrow [2021-02-28T23:59:59.999999+00:00]>)
+
+            >>> arrow.utcnow().span('week', week_start=6)
+            (<Arrow [2021-02-20T00:00:00+00:00]>, <Arrow [2021-02-26T23:59:59.999999+00:00]>)
+
+        """
+        if not 1 <= week_start <= 7:
+            raise ValueError("week_start argument must be between 1 and 7.")
+
+        util.validate_bounds(bounds)
+
+        frame_absolute, frame_relative, relative_steps = self._get_frames(frame)
+
+        if frame_absolute == "week":
+            attr = "day"
+        elif frame_absolute == "quarter":
+            attr = "month"
+        else:
+            attr = frame_absolute
+
+        floor = self
+        if not exact:
+            index = self._ATTRS.index(attr)
+            frames = self._ATTRS[: index + 1]
+
+            values = [getattr(self, f) for f in frames]
+
+            for _ in range(3 - len(values)):
+                values.append(1)
+
+            floor = self.__class__(*values, tzinfo=self.tzinfo)  # type: ignore[misc]
+
+            if frame_absolute == "week":
+                # if week_start is greater than self.isoweekday() go back one week by setting delta = 7
+                delta = 7 if week_start > self.isoweekday() else 0
+                floor = floor.shift(days=-(self.isoweekday() - week_start) - delta)
+            elif frame_absolute == "quarter":
+                floor = floor.shift(months=-((self.month - 1) % 3))
+
+        ceil = floor.shift(**{frame_relative: count * relative_steps})
+
+        if bounds[0] == "(":
+            floor = floor.shift(microseconds=+1)
+
+        if bounds[1] == ")":
+            ceil = ceil.shift(microseconds=-1)
+
+        return floor, ceil
+
+    def floor(self, frame: _T_FRAMES) -> "Arrow":
+        """Returns a new :class:`Arrow <arrow.arrow.Arrow>` object, representing the "floor"
+        of the timespan of the :class:`Arrow <arrow.arrow.Arrow>` object in a given timeframe.
+        Equivalent to the first element in the 2-tuple returned by
+        :func:`span <arrow.arrow.Arrow.span>`.
+
+        :param frame: the timeframe.  Can be any ``datetime`` property (day, hour, minute...).
+
+        Usage::
+
+            >>> arrow.utcnow().floor('hour')
+            <Arrow [2013-05-09T03:00:00+00:00]>
+
+        """
+
+        return self.span(frame)[0]
+
+    def ceil(self, frame: _T_FRAMES) -> "Arrow":
+        """Returns a new :class:`Arrow <arrow.arrow.Arrow>` object, representing the "ceiling"
+        of the timespan of the :class:`Arrow <arrow.arrow.Arrow>` object in a given timeframe.
+        Equivalent to the second element in the 2-tuple returned by
+        :func:`span <arrow.arrow.Arrow.span>`.
+
+        :param frame: the timeframe.  Can be any ``datetime`` property (day, hour, minute...).
+
+        Usage::
+
+            >>> arrow.utcnow().ceil('hour')
+            <Arrow [2013-05-09T03:59:59.999999+00:00]>
+
+        """
+
+        return self.span(frame)[1]
+
+    @classmethod
+    def span_range(
+        cls,
+        frame: _T_FRAMES,
+        start: dt_datetime,
+        end: dt_datetime,
+        tz: Optional[TZ_EXPR] = None,
+        limit: Optional[int] = None,
+        bounds: _BOUNDS = "[)",
+        exact: bool = False,
+    ) -> Iterable[Tuple["Arrow", "Arrow"]]:
+        """Returns an iterator of tuples, each :class:`Arrow <arrow.arrow.Arrow>` objects,
+        representing a series of timespans between two inputs.
+
+        :param frame: The timeframe.  Can be any ``datetime`` property (day, hour, minute...).
+        :param start: A datetime expression, the start of the range.
+        :param end: (optional) A datetime expression, the end of the range.
+        :param tz: (optional) A :ref:`timezone expression <tz-expr>`.  Defaults to
+            ``start``'s timezone, or UTC if ``start`` is naive.
+        :param limit: (optional) A maximum number of tuples to return.
+        :param bounds: (optional) a ``str`` of either '()', '(]', '[)', or '[]' that specifies
+            whether to include or exclude the start and end values in each span in the range. '(' excludes
+            the start, '[' includes the start, ')' excludes the end, and ']' includes the end.
+            If the bounds are not specified, the default bound '[)' is used.
+        :param exact: (optional) whether to have the first timespan start exactly
+            at the time specified by ``start`` and the final span truncated
+            so as not to extend beyond ``end``.
+
+        **NOTE**: The ``end`` or ``limit`` must be provided.  Call with ``end`` alone to
+        return the entire range.  Call with ``limit`` alone to return a maximum # of results from
+        the start.  Call with both to cap a range at a maximum # of results.
+
+        **NOTE**: ``tz`` internally **replaces** the timezones of both ``start`` and ``end`` before
+        iterating.  As such, either call with naive objects and ``tz``, or aware objects from the
+        same timezone and no ``tz``.
+
+        Supported frame values: year, quarter, month, week, day, hour, minute, second, microsecond.
+
+        Recognized datetime expressions:
+
+            - An :class:`Arrow <arrow.arrow.Arrow>` object.
+            - A ``datetime`` object.
+
+        **NOTE**: Unlike Python's ``range``, ``end`` will *always* be included in the returned
+        iterator of timespans.
+
+        Usage:
+
+            >>> start = datetime(2013, 5, 5, 12, 30)
+            >>> end = datetime(2013, 5, 5, 17, 15)
+            >>> for r in arrow.Arrow.span_range('hour', start, end):
+            ...     print(r)
+            ...
+            (<Arrow [2013-05-05T12:00:00+00:00]>, <Arrow [2013-05-05T12:59:59.999999+00:00]>)
+            (<Arrow [2013-05-05T13:00:00+00:00]>, <Arrow [2013-05-05T13:59:59.999999+00:00]>)
+            (<Arrow [2013-05-05T14:00:00+00:00]>, <Arrow [2013-05-05T14:59:59.999999+00:00]>)
+            (<Arrow [2013-05-05T15:00:00+00:00]>, <Arrow [2013-05-05T15:59:59.999999+00:00]>)
+            (<Arrow [2013-05-05T16:00:00+00:00]>, <Arrow [2013-05-05T16:59:59.999999+00:00]>)
+            (<Arrow [2013-05-05T17:00:00+00:00]>, <Arrow [2013-05-05T17:59:59.999999+00:00]>)
+
+        """
+
+        tzinfo = cls._get_tzinfo(start.tzinfo if tz is None else tz)
+        start = cls.fromdatetime(start, tzinfo).span(frame, exact=exact)[0]
+        end = cls.fromdatetime(end, tzinfo)
+        _range = cls.range(frame, start, end, tz, limit)
+        if not exact:
+            for r in _range:
+                yield r.span(frame, bounds=bounds, exact=exact)
+
+        for r in _range:
+            floor, ceil = r.span(frame, bounds=bounds, exact=exact)
+            if ceil > end:
+                ceil = end
+                if bounds[1] == ")":
+                    ceil += relativedelta(microseconds=-1)
+            if floor == end:
+                break
+            elif floor + relativedelta(microseconds=-1) == end:
+                break
+            yield floor, ceil
+
+    @classmethod
+    def interval(
+        cls,
+        frame: _T_FRAMES,
+        start: dt_datetime,
+        end: dt_datetime,
+        interval: int = 1,
+        tz: Optional[TZ_EXPR] = None,
+        bounds: _BOUNDS = "[)",
+        exact: bool = False,
+    ) -> Iterable[Tuple["Arrow", "Arrow"]]:
+        """Returns an iterator of tuples, each :class:`Arrow <arrow.arrow.Arrow>` objects,
+        representing a series of intervals between two inputs.
+
+        :param frame: The timeframe.  Can be any ``datetime`` property (day, hour, minute...).
+        :param start: A datetime expression, the start of the range.
+        :param end: (optional) A datetime expression, the end of the range.
+        :param interval: (optional) Time interval for the given time frame.
+        :param tz: (optional) A timezone expression.  Defaults to UTC.
+        :param bounds: (optional) a ``str`` of either '()', '(]', '[)', or '[]' that specifies
+            whether to include or exclude the start and end values in the intervals. '(' excludes
+            the start, '[' includes the start, ')' excludes the end, and ']' includes the end.
+            If the bounds are not specified, the default bound '[)' is used.
+        :param exact: (optional) whether to have the first timespan start exactly
+            at the time specified by ``start`` and the final interval truncated
+            so as not to extend beyond ``end``.
+
+        Supported frame values: year, quarter, month, week, day, hour, minute, second
+
+        Recognized datetime expressions:
+
+            - An :class:`Arrow <arrow.arrow.Arrow>` object.
+            - A ``datetime`` object.
+
+        Recognized timezone expressions:
+
+            - A ``tzinfo`` object.
+            - A ``str`` describing a timezone, similar to 'US/Pacific', or 'Europe/Berlin'.
+            - A ``str`` in ISO 8601 style, as in '+07:00'.
+            - A ``str``, one of the following:  'local', 'utc', 'UTC'.
+
+        Usage:
+
+            >>> start = datetime(2013, 5, 5, 12, 30)
+            >>> end = datetime(2013, 5, 5, 17, 15)
+            >>> for r in arrow.Arrow.interval('hour', start, end, 2):
+            ...     print(r)
+            ...
+            (<Arrow [2013-05-05T12:00:00+00:00]>, <Arrow [2013-05-05T13:59:59.999999+00:00]>)
+            (<Arrow [2013-05-05T14:00:00+00:00]>, <Arrow [2013-05-05T15:59:59.999999+00:00]>)
+            (<Arrow [2013-05-05T16:00:00+00:00]>, <Arrow [2013-05-05T17:59:59.999999+00:0]>)
+        """
+        if interval < 1:
+            raise ValueError("interval has to be a positive integer")
+
+        spanRange = iter(
+            cls.span_range(frame, start, end, tz, bounds=bounds, exact=exact)
+        )
+        while True:
+            try:
+                intvlStart, intvlEnd = next(spanRange)
+                for _ in range(interval - 1):
+                    try:
+                        _, intvlEnd = next(spanRange)
+                    except StopIteration:
+                        continue
+                yield intvlStart, intvlEnd
+            except StopIteration:
+                return
+
+    # representations
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} [{self.__str__()}]>"
+
+    def __str__(self) -> str:
+        return self._datetime.isoformat()
+
+    def __format__(self, formatstr: str) -> str:
+        if len(formatstr) > 0:
+            return self.format(formatstr)
+
+        return str(self)
+
+    def __hash__(self) -> int:
+        return self._datetime.__hash__()
+
+    # attributes and properties
+
+    def __getattr__(self, name: str) -> int:
+        if name == "week":
+            return self.isocalendar()[1]
+
+        if name == "quarter":
+            return int((self.month - 1) / self._MONTHS_PER_QUARTER) + 1
+
+        if not name.startswith("_"):
+            value: Optional[int] = getattr(self._datetime, name, None)
+
+            if value is not None:
+                return value
+
+        return cast(int, object.__getattribute__(self, name))
+
+    @property
+    def tzinfo(self) -> dt_tzinfo:
+        """Gets the ``tzinfo`` of the :class:`Arrow <arrow.arrow.Arrow>` object.
+
+        Usage::
+
+            >>> arw=arrow.utcnow()
+            >>> arw.tzinfo
+            tzutc()
+
+        """
+
+        # In Arrow, `_datetime` cannot be naive.
+        return cast(dt_tzinfo, self._datetime.tzinfo)
+
+    @property
+    def datetime(self) -> dt_datetime:
+        """Returns a datetime representation of the :class:`Arrow <arrow.arrow.Arrow>` object.
+
+        Usage::
+
+            >>> arw=arrow.utcnow()
+            >>> arw.datetime
+            datetime.datetime(2019, 1, 24, 16, 35, 27, 276649, tzinfo=tzutc())
+
+        """
+
+        return self._datetime
+
+    @property
+    def naive(self) -> dt_datetime:
+        """Returns a naive datetime representation of the :class:`Arrow <arrow.arrow.Arrow>`
+        object.
+
+        Usage::
+
+            >>> nairobi = arrow.now('Africa/Nairobi')
+            >>> nairobi
+            <Arrow [2019-01-23T19:27:12.297999+03:00]>
+            >>> nairobi.naive
+            datetime.datetime(2019, 1, 23, 19, 27, 12, 297999)
+
+        """
+
+        return self._datetime.replace(tzinfo=None)
+
+    def timestamp(self) -> float:
+        """Returns a timestamp representation of the :class:`Arrow <arrow.arrow.Arrow>` object, in
+        UTC time.
+
+        Usage::
+
+            >>> arrow.utcnow().timestamp()
+            1616882340.256501
+
+        """
+
+        return self._datetime.timestamp()
+
+    @property
+    def int_timestamp(self) -> int:
+        """Returns an integer timestamp representation of the :class:`Arrow <arrow.arrow.Arrow>` object, in
+        UTC time.
+
+        Usage::
+
+            >>> arrow.utcnow().int_timestamp
+            1548260567
+
+        """
+
+        return int(self.timestamp())
+
+    @property
+    def float_timestamp(self) -> float:
+        """Returns a floating-point timestamp representation of the :class:`Arrow <arrow.arrow.Arrow>`
+        object, in UTC time.
+
+        Usage::
+
+            >>> arrow.utcnow().float_timestamp
+            1548260516.830896
+
+        """
+
+        return self.timestamp()
+
+    @property
+    def fold(self) -> int:
+        """Returns the ``fold`` value of the :class:`Arrow <arrow.arrow.Arrow>` object."""
+
+        return self._datetime.fold
+
+    @property
+    def ambiguous(self) -> bool:
+        """Indicates whether the :class:`Arrow <arrow.arrow.Arrow>` object is a repeated wall time in the current
+        timezone.
+
+        """
+
+        return dateutil_tz.datetime_ambiguous(self._datetime)
+
+    @property
+    def imaginary(self) -> bool:
+        """Indicates whether the :class: `Arrow <arrow.arrow.Arrow>` object exists in the current timezone."""
+
+        return not dateutil_tz.datetime_exists(self._datetime)
+
+    # mutation and duplication.
+
+    def clone(self) -> "Arrow":
+        """Returns a new :class:`Arrow <arrow.arrow.Arrow>` object, cloned from the current one.
+
+        Usage:
+
+            >>> arw = arrow.utcnow()
+            >>> cloned = arw.clone()
+
+        """
+
+        return self.fromdatetime(self._datetime)
+
+    def replace(self, **kwargs: Any) -> "Arrow":
+        """Returns a new :class:`Arrow <arrow.arrow.Arrow>` object with attributes updated
+        according to inputs.
+
+        Use property names to set their value absolutely::
+
+            >>> import arrow
+            >>> arw = arrow.utcnow()
+            >>> arw
+            <Arrow [2013-05-11T22:27:34.787885+00:00]>
+            >>> arw.replace(year=2014, month=6)
+            <Arrow [2014-06-11T22:27:34.787885+00:00]>
+
+        You can also replace the timezone without conversion, using a
+        :ref:`timezone expression <tz-expr>`::
+
+            >>> arw.replace(tzinfo=tz.tzlocal())
+            <Arrow [2013-05-11T22:27:34.787885-07:00]>
+
+        """
+
+        absolute_kwargs = {}
+
+        for key, value in kwargs.items():
+            if key in self._ATTRS:
+                absolute_kwargs[key] = value
+            elif key in ["week", "quarter"]:
+                raise ValueError(f"Setting absolute {key} is not supported.")
+            elif key not in ["tzinfo", "fold"]:
+                raise ValueError(f"Unknown attribute: {key!r}.")
+
+        current = self._datetime.replace(**absolute_kwargs)
+
+        tzinfo = kwargs.get("tzinfo")
+
+        if tzinfo is not None:
+            tzinfo = self._get_tzinfo(tzinfo)
+            current = current.replace(tzinfo=tzinfo)
+
+        fold = kwargs.get("fold")
+
+        if fold is not None:
+            current = current.replace(fold=fold)
+
+        return self.fromdatetime(current)
+
+    def shift(self, **kwargs: Any) -> "Arrow":
+        """Returns a new :class:`Arrow <arrow.arrow.Arrow>` object with attributes updated
+        according to inputs.
+
+        Use pluralized property names to relatively shift their current value:
+
+        >>> import arrow
+        >>> arw = arrow.utcnow()
+        >>> arw
+        <Arrow [2013-05-11T22:27:34.787885+00:00]>
+        >>> arw.shift(years=1, months=-1)
+        <Arrow [2014-04-11T22:27:34.787885+00:00]>
+
+        Day-of-the-week relative shifting can use either Python's weekday numbers
+        (Monday = 0, Tuesday = 1 .. Sunday = 6) or using dateutil.relativedelta's
+        day instances (MO, TU .. SU).  When using weekday numbers, the returned
+        date will always be greater than or equal to the starting date.
+
+        Using the above code (which is a Saturday) and asking it to shift to Saturday:
+
+        >>> arw.shift(weekday=5)
+        <Arrow [2013-05-11T22:27:34.787885+00:00]>
+
+        While asking for a Monday:
+
+        >>> arw.shift(weekday=0)
+        <Arrow [2013-05-13T22:27:34.787885+00:00]>
+
+        """
+
+        relative_kwargs = {}
+        additional_attrs = ["weeks", "quarters", "weekday"]
+
+        for key, value in kwargs.items():
+            if key in self._ATTRS_PLURAL or key in additional_attrs:
+                relative_kwargs[key] = value
+            else:
+                supported_attr = ", ".join(self._ATTRS_PLURAL + additional_attrs)
+                raise ValueError(
+                    f"Invalid shift time frame. Please select one of the following: {supported_attr}."
+                )
+
+        # core datetime does not support quarters, translate to months.
+        relative_kwargs.setdefault("months", 0)
+        relative_kwargs["months"] += (
+            relative_kwargs.pop("quarters", 0) * self._MONTHS_PER_QUARTER
+        )
+
+        current = self._datetime + relativedelta(**relative_kwargs)
+
+        if not dateutil_tz.datetime_exists(current):
+            current = dateutil_tz.resolve_imaginary(current)
+
+        return self.fromdatetime(current)
+
+    def to(self, tz: TZ_EXPR) -> "Arrow":
+        """Returns a new :class:`Arrow <arrow.arrow.Arrow>` object, converted
+        to the target timezone.
+
+        :param tz: A :ref:`timezone expression <tz-expr>`.
+
+        Usage::
+
+            >>> utc = arrow.utcnow()
+            >>> utc
+            <Arrow [2013-05-09T03:49:12.311072+00:00]>
+
+            >>> utc.to('US/Pacific')
+            <Arrow [2013-05-08T20:49:12.311072-07:00]>
+
+            >>> utc.to(tz.tzlocal())
+            <Arrow [2013-05-08T20:49:12.311072-07:00]>
+
+            >>> utc.to('-07:00')
+            <Arrow [2013-05-08T20:49:12.311072-07:00]>
+
+            >>> utc.to('local')
+            <Arrow [2013-05-08T20:49:12.311072-07:00]>
+
+            >>> utc.to('local').to('utc')
+            <Arrow [2013-05-09T03:49:12.311072+00:00]>
+
+        """
+
+        if not isinstance(tz, dt_tzinfo):
+            tz = parser.TzinfoParser.parse(tz)
+
+        dt = self._datetime.astimezone(tz)
+
+        return self.__class__(
+            dt.year,
+            dt.month,
+            dt.day,
+            dt.hour,
+            dt.minute,
+            dt.second,
+            dt.microsecond,
+            dt.tzinfo,
+            fold=getattr(dt, "fold", 0),
+        )
+
+    # string output and formatting
+
+    def format(
+        self, fmt: str = "YYYY-MM-DD HH:mm:ssZZ", locale: str = DEFAULT_LOCALE
+    ) -> str:
+        """Returns a string representation of the :class:`Arrow <arrow.arrow.Arrow>` object,
+        formatted according to the provided format string.
+
+        :param fmt: the format string.
+        :param locale: the locale to format.
+
+        Usage::
+
+            >>> arrow.utcnow().format('YYYY-MM-DD HH:mm:ss ZZ')
+            '2013-05-09 03:56:47 -00:00'
+
+            >>> arrow.utcnow().format('X')
+            '1368071882'
+
+            >>> arrow.utcnow().format('MMMM DD, YYYY')
+            'May 09, 2013'
+
+            >>> arrow.utcnow().format()
+            '2013-05-09 03:56:47 -00:00'
+
+        """
+
+        return formatter.DateTimeFormatter(locale).format(self._datetime, fmt)
+
+    def humanize(
+        self,
+        other: Union["Arrow", dt_datetime, None] = None,
+        locale: str = DEFAULT_LOCALE,
+        only_distance: bool = False,
+        granularity: Union[_GRANULARITY, List[_GRANULARITY]] = "auto",
+    ) -> str:
+        """Returns a localized, humanized representation of a relative difference in time.
+
+        :param other: (optional) an :class:`Arrow <arrow.arrow.Arrow>` or ``datetime`` object.
+            Defaults to now in the current :class:`Arrow <arrow.arrow.Arrow>` object's timezone.
+        :param locale: (optional) a ``str`` specifying a locale.  Defaults to 'en-us'.
+        :param only_distance: (optional) returns only time difference eg: "11 seconds" without "in" or "ago" part.
+        :param granularity: (optional) defines the precision of the output. Set it to strings 'second', 'minute',
+                           'hour', 'day', 'week', 'month' or 'year' or a list of any combination of these strings
+
+        Usage::
+
+            >>> earlier = arrow.utcnow().shift(hours=-2)
+            >>> earlier.humanize()
+            '2 hours ago'
+
+            >>> later = earlier.shift(hours=4)
+            >>> later.humanize(earlier)
+            'in 4 hours'
+
+        """
+
+        locale_name = locale
+        locale = locales.get_locale(locale)
+
+        if other is None:
+            utc = dt_datetime.utcnow().replace(tzinfo=dateutil_tz.tzutc())
+            dt = utc.astimezone(self._datetime.tzinfo)
+
+        elif isinstance(other, Arrow):
+            dt = other._datetime
+
+        elif isinstance(other, dt_datetime):
+            if other.tzinfo is None:
+                dt = other.replace(tzinfo=self._datetime.tzinfo)
+            else:
+                dt = other.astimezone(self._datetime.tzinfo)
+
+        else:
+            raise TypeError(
+                f"Invalid 'other' argument of type {type(other).__name__!r}. "
+                "Argument must be of type None, Arrow, or datetime."
+            )
+
+        if isinstance(granularity, list) and len(granularity) == 1:
+            granularity = granularity[0]
+
+        _delta = int(round((self._datetime - dt).total_seconds()))
+        sign = -1 if _delta < 0 else 1
+        delta_second = diff = abs(_delta)
+
+        try:
+            if granularity == "auto":
+                if diff < 10:
+                    return locale.describe("now", only_distance=only_distance)
+
+                if diff < self._SECS_PER_MINUTE:
+                    seconds = sign * delta_second
+                    return locale.describe(
+                        "seconds", seconds, only_distance=only_distance
+                    )
+
+                elif diff < self._SECS_PER_MINUTE * 2:
+                    return locale.describe("minute", sign, only_distance=only_distance)
+                elif diff < self._SECS_PER_HOUR:
+                    minutes = sign * max(delta_second // self._SECS_PER_MINUTE, 2)
+                    return locale.describe(
+                        "minutes", minutes, only_distance=only_distance
+                    )
+
+                elif diff < self._SECS_PER_HOUR * 2:
+                    return locale.describe("hour", sign, only_distance=only_distance)
+                elif diff < self._SECS_PER_DAY:
+                    hours = sign * max(delta_second // self._SECS_PER_HOUR, 2)
+                    return locale.describe("hours", hours, only_distance=only_distance)
+                elif diff < self._SECS_PER_DAY * 2:
+                    return locale.describe("day", sign, only_distance=only_distance)
+                elif diff < self._SECS_PER_WEEK:
+                    days = sign * max(delta_second // self._SECS_PER_DAY, 2)
+                    return locale.describe("days", days, only_distance=only_distance)
+
+                elif diff < self._SECS_PER_WEEK * 2:
+                    return locale.describe("week", sign, only_distance=only_distance)
+                elif diff < self._SECS_PER_MONTH:
+                    weeks = sign * max(delta_second // self._SECS_PER_WEEK, 2)
+                    return locale.describe("weeks", weeks, only_distance=only_distance)
+
+                elif diff < self._SECS_PER_MONTH * 2:
+                    return locale.describe("month", sign, only_distance=only_distance)
+                elif diff < self._SECS_PER_YEAR:
+                    # TODO revisit for humanization during leap years
+                    self_months = self._datetime.year * 12 + self._datetime.month
+                    other_months = dt.year * 12 + dt.month
+
+                    months = sign * max(abs(other_months - self_months), 2)
+
+                    return locale.describe(
+                        "months", months, only_distance=only_distance
+                    )
+
+                elif diff < self._SECS_PER_YEAR * 2:
+                    return locale.describe("year", sign, only_distance=only_distance)
+                else:
+                    years = sign * max(delta_second // self._SECS_PER_YEAR, 2)
+                    return locale.describe("years", years, only_distance=only_distance)
+
+            elif isinstance(granularity, str):
+                granularity = cast(TimeFrameLiteral, granularity)  # type: ignore[assignment]
+
+                if granularity == "second":
+                    delta = sign * float(delta_second)
+                    if abs(delta) < 2:
+                        return locale.describe("now", only_distance=only_distance)
+                elif granularity == "minute":
+                    delta = sign * delta_second / self._SECS_PER_MINUTE
+                elif granularity == "hour":
+                    delta = sign * delta_second / self._SECS_PER_HOUR
+                elif granularity == "day":
+                    delta = sign * delta_second / self._SECS_PER_DAY
+                elif granularity == "week":
+                    delta = sign * delta_second / self._SECS_PER_WEEK
+                elif granularity == "month":
+                    delta = sign * delta_second / self._SECS_PER_MONTH
+                elif granularity == "quarter":
+                    delta = sign * delta_second / self._SECS_PER_QUARTER
+                elif granularity == "year":
+                    delta = sign * delta_second / self._SECS_PER_YEAR
+                else:
+                    raise ValueError(
+                        "Invalid level of granularity. "
+                        "Please select between 'second', 'minute', 'hour', 'day', 'week', 'month', 'quarter' or 'year'."
+                    )
+
+                if trunc(abs(delta)) != 1:
+                    granularity += "s"  # type: ignore[assignment]
+                return locale.describe(granularity, delta, only_distance=only_distance)
+
+            else:
+                if not granularity:
+                    raise ValueError(
+                        "Empty granularity list provided. "
+                        "Please select one or more from 'second', 'minute', 'hour', 'day', 'week', 'month', 'quarter', 'year'."
+                    )
+
+                timeframes: List[Tuple[TimeFrameLiteral, float]] = []
+
+                def gather_timeframes(_delta: float, _frame: TimeFrameLiteral) -> float:
+                    if _frame in granularity:
+                        value = sign * _delta / self._SECS_MAP[_frame]
+                        _delta %= self._SECS_MAP[_frame]
+                        if trunc(abs(value)) != 1:
+                            timeframes.append(
+                                (cast(TimeFrameLiteral, _frame + "s"), value)
+                            )
+                        else:
+                            timeframes.append((_frame, value))
+                    return _delta
+
+                delta = float(delta_second)
+                frames: Tuple[TimeFrameLiteral, ...] = (
+                    "year",
+                    "quarter",
+                    "month",
+                    "week",
+                    "day",
+                    "hour",
+                    "minute",
+                    "second",
+                )
+                for frame in frames:
+                    delta = gather_timeframes(delta, frame)
+
+                if len(timeframes) < len(granularity):
+                    raise ValueError(
+                        "Invalid level of granularity. "
+                        "Please select between 'second', 'minute', 'hour', 'day', 'week', 'month', 'quarter' or 'year'."
+                    )
+
+                return locale.describe_multi(timeframes, only_distance=only_distance)
+
+        except KeyError as e:
+            raise ValueError(
+                f"Humanization of the {e} granularity is not currently translated in the {locale_name!r} locale. "
+                "Please consider making a contribution to this locale."
+            )
+
+    def dehumanize(self, input_string: str, locale: str = "en_us") -> "Arrow":
+        """Returns a new :class:`Arrow <arrow.arrow.Arrow>` object, that represents
+        the time difference relative to the attributes of the
+        :class:`Arrow <arrow.arrow.Arrow>` object.
+
+        :param timestring: a ``str`` representing a humanized relative time.
+        :param locale: (optional) a ``str`` specifying a locale.  Defaults to 'en-us'.
+
+        Usage::
+
+                >>> arw = arrow.utcnow()
+                >>> arw
+                <Arrow [2021-04-20T22:27:34.787885+00:00]>
+                >>> earlier = arw.dehumanize("2 days ago")
+                >>> earlier
+                <Arrow [2021-04-18T22:27:34.787885+00:00]>
+
+                >>> arw = arrow.utcnow()
+                >>> arw
+                <Arrow [2021-04-20T22:27:34.787885+00:00]>
+                >>> later = arw.dehumanize("in a month")
+                >>> later
+                <Arrow [2021-05-18T22:27:34.787885+00:00]>
+
+        """
+
+        # Create a locale object based off given local
+        locale_obj = locales.get_locale(locale)
+
+        # Check to see if locale is supported
+        normalized_locale_name = locale.lower().replace("_", "-")
+
+        if normalized_locale_name not in DEHUMANIZE_LOCALES:
+            raise ValueError(
+                f"Dehumanize does not currently support the {locale} locale, please consider making a contribution to add support for this locale."
+            )
+
+        current_time = self.fromdatetime(self._datetime)
+
+        # Create an object containing the relative time info
+        time_object_info = dict.fromkeys(
+            ["seconds", "minutes", "hours", "days", "weeks", "months", "years"], 0
+        )
+
+        # Create an object representing if unit has been seen
+        unit_visited = dict.fromkeys(
+            ["now", "seconds", "minutes", "hours", "days", "weeks", "months", "years"],
+            False,
+        )
+
+        # Create a regex pattern object for numbers
+        num_pattern = re.compile(r"\d+")
+
+        # Search input string for each time unit within locale
+        for unit, unit_object in locale_obj.timeframes.items():
+            # Need to check the type of unit_object to create the correct dictionary
+            if isinstance(unit_object, Mapping):
+                strings_to_search = unit_object
+            else:
+                strings_to_search = {unit: str(unit_object)}
+
+            # Search for any matches that exist for that locale's unit.
+            # Needs to cycle all through strings as some locales have strings that
+            # could overlap in a regex match, since input validation isn't being performed.
+            for time_delta, time_string in strings_to_search.items():
+                # Replace {0} with regex \d representing digits
+                search_string = str(time_string)
+                search_string = search_string.format(r"\d+")
+
+                # Create search pattern and find within string
+                pattern = re.compile(rf"(^|\b|\d){search_string}")
+                match = pattern.search(input_string)
+
+                # If there is no match continue to next iteration
+                if not match:
+                    continue
+
+                match_string = match.group()
+                num_match = num_pattern.search(match_string)
+
+                # If no number matches
+                # Need for absolute value as some locales have signs included in their objects
+                if not num_match:
+                    change_value = (
+                        1 if not time_delta.isnumeric() else abs(int(time_delta))
+                    )
+                else:
+                    change_value = int(num_match.group())
+
+                # No time to update if now is the unit
+                if unit == "now":
+                    unit_visited[unit] = True
+                    continue
+
+                # Add change value to the correct unit (incorporates the plurality that exists within timeframe i.e second v.s seconds)
+                time_unit_to_change = str(unit)
+                time_unit_to_change += (
+                    "s" if (str(time_unit_to_change)[-1] != "s") else ""
+                )
+                time_object_info[time_unit_to_change] = change_value
+                unit_visited[time_unit_to_change] = True
+
+        # Assert error if string does not modify any units
+        if not any([True for k, v in unit_visited.items() if v]):
+            raise ValueError(
+                "Input string not valid. Note: Some locales do not support the week granularity in Arrow. "
+                "If you are attempting to use the week granularity on an unsupported locale, this could be the cause of this error."
+            )
+
+        # Sign logic
+        future_string = locale_obj.future
+        future_string = future_string.format(".*")
+        future_pattern = re.compile(rf"^{future_string}$")
+        future_pattern_match = future_pattern.findall(input_string)
+
+        past_string = locale_obj.past
+        past_string = past_string.format(".*")
+        past_pattern = re.compile(rf"^{past_string}$")
+        past_pattern_match = past_pattern.findall(input_string)
+
+        # If a string contains the now unit, there will be no relative units, hence the need to check if the now unit
+        # was visited before raising a ValueError
+        if past_pattern_match:
+            sign_val = -1
+        elif future_pattern_match:
+            sign_val = 1
+        elif unit_visited["now"]:
+            sign_val = 0
+        else:
+            raise ValueError(
+                "Invalid input String. String does not contain any relative time information. "
+                "String should either represent a time in the future or a time in the past. "
+                "Ex: 'in 5 seconds' or '5 seconds ago'."
+            )
+
+        time_changes = {k: sign_val * v for k, v in time_object_info.items()}
+
+        return current_time.shift(**time_changes)
+
+    # query functions
+
+    def is_between(
+        self,
+        start: "Arrow",
+        end: "Arrow",
+        bounds: _BOUNDS = "()",
+    ) -> bool:
+        """Returns a boolean denoting whether the :class:`Arrow <arrow.arrow.Arrow>` object is between
+        the start and end limits.
+
+        :param start: an :class:`Arrow <arrow.arrow.Arrow>` object.
+        :param end: an :class:`Arrow <arrow.arrow.Arrow>` object.
+        :param bounds: (optional) a ``str`` of either '()', '(]', '[)', or '[]' that specifies
+            whether to include or exclude the start and end values in the range. '(' excludes
+            the start, '[' includes the start, ')' excludes the end, and ']' includes the end.
+            If the bounds are not specified, the default bound '()' is used.
+
+        Usage::
+
+            >>> start = arrow.get(datetime(2013, 5, 5, 12, 30, 10))
+            >>> end = arrow.get(datetime(2013, 5, 5, 12, 30, 36))
+            >>> arrow.get(datetime(2013, 5, 5, 12, 30, 27)).is_between(start, end)
+            True
+
+            >>> start = arrow.get(datetime(2013, 5, 5))
+            >>> end = arrow.get(datetime(2013, 5, 8))
+            >>> arrow.get(datetime(2013, 5, 8)).is_between(start, end, '[]')
+            True
+
+            >>> start = arrow.get(datetime(2013, 5, 5))
+            >>> end = arrow.get(datetime(2013, 5, 8))
+            >>> arrow.get(datetime(2013, 5, 8)).is_between(start, end, '[)')
+            False
+
+        """
+
+        util.validate_bounds(bounds)
+
+        if not isinstance(start, Arrow):
+            raise TypeError(
+                f"Cannot parse start date argument type of {type(start)!r}."
+            )
+
+        if not isinstance(end, Arrow):
+            raise TypeError(f"Cannot parse end date argument type of {type(start)!r}.")
+
+        include_start = bounds[0] == "["
+        include_end = bounds[1] == "]"
+
+        target_ts = self.float_timestamp
+        start_ts = start.float_timestamp
+        end_ts = end.float_timestamp
+
+        return (
+            (start_ts <= target_ts <= end_ts)
+            and (include_start or start_ts < target_ts)
+            and (include_end or target_ts < end_ts)
+        )
+
+    # datetime methods
+
+    def date(self) -> date:
+        """Returns a ``date`` object with the same year, month and day.
+
+        Usage::
+
+            >>> arrow.utcnow().date()
+            datetime.date(2019, 1, 23)
+
+        """
+
+        return self._datetime.date()
+
+    def time(self) -> dt_time:
+        """Returns a ``time`` object with the same hour, minute, second, microsecond.
+
+        Usage::
+
+            >>> arrow.utcnow().time()
+            datetime.time(12, 15, 34, 68352)
+
+        """
+
+        return self._datetime.time()
+
+    def timetz(self) -> dt_time:
+        """Returns a ``time`` object with the same hour, minute, second, microsecond and
+        tzinfo.
+
+        Usage::
+
+            >>> arrow.utcnow().timetz()
+            datetime.time(12, 5, 18, 298893, tzinfo=tzutc())
+
+        """
+
+        return self._datetime.timetz()
+
+    def astimezone(self, tz: Optional[dt_tzinfo]) -> dt_datetime:
+        """Returns a ``datetime`` object, converted to the specified timezone.
+
+        :param tz: a ``tzinfo`` object.
+
+        Usage::
+
+            >>> pacific=arrow.now('US/Pacific')
+            >>> nyc=arrow.now('America/New_York').tzinfo
+            >>> pacific.astimezone(nyc)
+            datetime.datetime(2019, 1, 20, 10, 24, 22, 328172, tzinfo=tzfile('/usr/share/zoneinfo/America/New_York'))
+
+        """
+
+        return self._datetime.astimezone(tz)
+
+    def utcoffset(self) -> Optional[timedelta]:
+        """Returns a ``timedelta`` object representing the whole number of minutes difference from
+        UTC time.
+
+        Usage::
+
+            >>> arrow.now('US/Pacific').utcoffset()
+            datetime.timedelta(-1, 57600)
+
+        """
+
+        return self._datetime.utcoffset()
+
+    def dst(self) -> Optional[timedelta]:
+        """Returns the daylight savings time adjustment.
+
+        Usage::
+
+            >>> arrow.utcnow().dst()
+            datetime.timedelta(0)
+
+        """
+
+        return self._datetime.dst()
+
+    def timetuple(self) -> struct_time:
+        """Returns a ``time.struct_time``, in the current timezone.
+
+        Usage::
+
+            >>> arrow.utcnow().timetuple()
+            time.struct_time(tm_year=2019, tm_mon=1, tm_mday=20, tm_hour=15, tm_min=17, tm_sec=8, tm_wday=6, tm_yday=20, tm_isdst=0)
+
+        """
+
+        return self._datetime.timetuple()
+
+    def utctimetuple(self) -> struct_time:
+        """Returns a ``time.struct_time``, in UTC time.
+
+        Usage::
+
+            >>> arrow.utcnow().utctimetuple()
+            time.struct_time(tm_year=2019, tm_mon=1, tm_mday=19, tm_hour=21, tm_min=41, tm_sec=7, tm_wday=5, tm_yday=19, tm_isdst=0)
+
+        """
+
+        return self._datetime.utctimetuple()
+
+    def toordinal(self) -> int:
+        """Returns the proleptic Gregorian ordinal of the date.
+
+        Usage::
+
+            >>> arrow.utcnow().toordinal()
+            737078
+
+        """
+
+        return self._datetime.toordinal()
+
+    def weekday(self) -> int:
+        """Returns the day of the week as an integer (0-6).
+
+        Usage::
+
+            >>> arrow.utcnow().weekday()
+            5
+
+        """
+
+        return self._datetime.weekday()
+
+    def isoweekday(self) -> int:
+        """Returns the ISO day of the week as an integer (1-7).
+
+        Usage::
+
+            >>> arrow.utcnow().isoweekday()
+            6
+
+        """
+
+        return self._datetime.isoweekday()
+
+    def isocalendar(self) -> Tuple[int, int, int]:
+        """Returns a 3-tuple, (ISO year, ISO week number, ISO weekday).
+
+        Usage::
+
+            >>> arrow.utcnow().isocalendar()
+            (2019, 3, 6)
+
+        """
+
+        return self._datetime.isocalendar()
+
+    def isoformat(self, sep: str = "T", timespec: str = "auto") -> str:
+        """Returns an ISO 8601 formatted representation of the date and time.
+
+        Usage::
+
+            >>> arrow.utcnow().isoformat()
+            '2019-01-19T18:30:52.442118+00:00'
+
+        """
+
+        return self._datetime.isoformat(sep, timespec)
+
+    def ctime(self) -> str:
+        """Returns a ctime formatted representation of the date and time.
+
+        Usage::
+
+            >>> arrow.utcnow().ctime()
+            'Sat Jan 19 18:26:50 2019'
+
+        """
+
+        return self._datetime.ctime()
+
+    def strftime(self, format: str) -> str:
+        """Formats in the style of ``datetime.strftime``.
+
+        :param format: the format string.
+
+        Usage::
+
+            >>> arrow.utcnow().strftime('%d-%m-%Y %H:%M:%S')
+            '23-01-2019 12:28:17'
+
+        """
+
+        return self._datetime.strftime(format)
+
+    def for_json(self) -> str:
+        """Serializes for the ``for_json`` protocol of simplejson.
+
+        Usage::
+
+            >>> arrow.utcnow().for_json()
+            '2019-01-19T18:25:36.760079+00:00'
+
+        """
+
+        return self.isoformat()
+
+    # math
+
+    def __add__(self, other: Any) -> "Arrow":
+        if isinstance(other, (timedelta, relativedelta)):
+            return self.fromdatetime(self._datetime + other, self._datetime.tzinfo)
+
+        return NotImplemented
+
+    def __radd__(self, other: Union[timedelta, relativedelta]) -> "Arrow":
+        return self.__add__(other)
+
+    @overload
+    def __sub__(self, other: Union[timedelta, relativedelta]) -> "Arrow":
+        pass  # pragma: no cover
+
+    @overload
+    def __sub__(self, other: Union[dt_datetime, "Arrow"]) -> timedelta:
+        pass  # pragma: no cover
+
+    def __sub__(self, other: Any) -> Union[timedelta, "Arrow"]:
+        if isinstance(other, (timedelta, relativedelta)):
+            return self.fromdatetime(self._datetime - other, self._datetime.tzinfo)
+
+        elif isinstance(other, dt_datetime):
+            return self._datetime - other
+
+        elif isinstance(other, Arrow):
+            return self._datetime - other._datetime
+
+        return NotImplemented
+
+    def __rsub__(self, other: Any) -> timedelta:
+        if isinstance(other, dt_datetime):
+            return other - self._datetime
+
+        return NotImplemented
+
+    # comparisons
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, (Arrow, dt_datetime)):
+            return False
+
+        return self._datetime == self._get_datetime(other)
+
+    def __ne__(self, other: Any) -> bool:
+        if not isinstance(other, (Arrow, dt_datetime)):
+            return True
+
+        return not self.__eq__(other)
+
+    def __gt__(self, other: Any) -> bool:
+        if not isinstance(other, (Arrow, dt_datetime)):
+            return NotImplemented
+
+        return self._datetime > self._get_datetime(other)
+
+    def __ge__(self, other: Any) -> bool:
+        if not isinstance(other, (Arrow, dt_datetime)):
+            return NotImplemented
+
+        return self._datetime >= self._get_datetime(other)
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, (Arrow, dt_datetime)):
+            return NotImplemented
+
+        return self._datetime < self._get_datetime(other)
+
+    def __le__(self, other: Any) -> bool:
+        if not isinstance(other, (Arrow, dt_datetime)):
+            return NotImplemented
+
+        return self._datetime <= self._get_datetime(other)
+
+    # internal methods
+    @staticmethod
+    def _get_tzinfo(tz_expr: Optional[TZ_EXPR]) -> dt_tzinfo:
+        """Get normalized tzinfo object from various inputs."""
+        if tz_expr is None:
+            return dateutil_tz.tzutc()
+        if isinstance(tz_expr, dt_tzinfo):
+            return tz_expr
+        else:
+            try:
+                return parser.TzinfoParser.parse(tz_expr)
+            except parser.ParserError:
+                raise ValueError(f"{tz_expr!r} not recognized as a timezone.")
+
+    @classmethod
+    def _get_datetime(
+        cls, expr: Union["Arrow", dt_datetime, int, float, str]
+    ) -> dt_datetime:
+        """Get datetime object from a specified expression."""
+        if isinstance(expr, Arrow):
+            return expr.datetime
+        elif isinstance(expr, dt_datetime):
+            return expr
+        elif util.is_timestamp(expr):
+            timestamp = float(expr)
+            return cls.utcfromtimestamp(timestamp).datetime
+        else:
+            raise ValueError(f"{expr!r} not recognized as a datetime or timestamp.")
+
+    @classmethod
+    def _get_frames(cls, name: _T_FRAMES) -> Tuple[str, str, int]:
+        """Finds relevant timeframe and steps for use in range and span methods.
+
+        Returns a 3 element tuple in the form (frame, plural frame, step), for example ("day", "days", 1)
+
+        """
+        if name in cls._ATTRS:
+            return name, f"{name}s", 1
+        elif name[-1] == "s" and name[:-1] in cls._ATTRS:
+            return name[:-1], name, 1
+        elif name in ["week", "weeks"]:
+            return "week", "weeks", 1
+        elif name in ["quarter", "quarters"]:
+            return "quarter", "months", 3
+        else:
+            supported = ", ".join(
+                [
+                    "year(s)",
+                    "month(s)",
+                    "day(s)",
+                    "hour(s)",
+                    "minute(s)",
+                    "second(s)",
+                    "microsecond(s)",
+                    "week(s)",
+                    "quarter(s)",
+                ]
+            )
+            raise ValueError(
+                f"Range or span over frame {name} not supported. Supported frames: {supported}."
+            )
+
+    @classmethod
+    def _get_iteration_params(cls, end: Any, limit: Optional[int]) -> Tuple[Any, int]:
+        """Sets default end and limit values for range method."""
+        if end is None:
+            if limit is None:
+                raise ValueError("One of 'end' or 'limit' is required.")
+
+            return cls.max, limit
+
+        else:
+            if limit is None:
+                return end, sys.maxsize
+            return end, limit
+
+    @staticmethod
+    def _is_last_day_of_month(date: "Arrow") -> bool:
+        """Returns a boolean indicating whether the datetime is the last day of the month."""
+        return date.day == calendar.monthrange(date.year, date.month)[1]
+
+
+Arrow.min = Arrow.fromdatetime(dt_datetime.min)
+Arrow.max = Arrow.fromdatetime(dt_datetime.max)

venv/Lib/site-packages/arrow/constants.py

@@ -0,0 +1,177 @@
+"""Constants used internally in arrow."""
+
+import sys
+from datetime import datetime
+
+if sys.version_info < (3, 8):  # pragma: no cover
+    from typing_extensions import Final
+else:
+    from typing import Final  # pragma: no cover
+
+# datetime.max.timestamp() errors on Windows, so we must hardcode
+# the highest possible datetime value that can output a timestamp.
+# tl;dr platform-independent max timestamps are hard to form
+# See: https://stackoverflow.com/q/46133223
+try:
+    # Get max timestamp. Works on POSIX-based systems like Linux and macOS,
+    # but will trigger an OverflowError, ValueError, or OSError on Windows
+    _MAX_TIMESTAMP = datetime.max.timestamp()
+except (OverflowError, ValueError, OSError):  # pragma: no cover
+    # Fallback for Windows and 32-bit systems if initial max timestamp call fails
+    # Must get max value of ctime on Windows based on architecture (x32 vs x64)
+    # https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64
+    # Note: this may occur on both 32-bit Linux systems (issue #930) along with Windows systems
+    is_64bits = sys.maxsize > 2**32
+    _MAX_TIMESTAMP = (
+        datetime(3000, 1, 1, 23, 59, 59, 999999).timestamp()
+        if is_64bits
+        else datetime(2038, 1, 1, 23, 59, 59, 999999).timestamp()
+    )
+
+MAX_TIMESTAMP: Final[float] = _MAX_TIMESTAMP
+MAX_TIMESTAMP_MS: Final[float] = MAX_TIMESTAMP * 1000
+MAX_TIMESTAMP_US: Final[float] = MAX_TIMESTAMP * 1_000_000
+
+MAX_ORDINAL: Final[int] = datetime.max.toordinal()
+MIN_ORDINAL: Final[int] = 1
+
+DEFAULT_LOCALE: Final[str] = "en-us"
+
+# Supported dehumanize locales
+DEHUMANIZE_LOCALES = {
+    "en",
+    "en-us",
+    "en-gb",
+    "en-au",
+    "en-be",
+    "en-jp",
+    "en-za",
+    "en-ca",
+    "en-ph",
+    "fr",
+    "fr-fr",
+    "fr-ca",
+    "it",
+    "it-it",
+    "es",
+    "es-es",
+    "el",
+    "el-gr",
+    "ja",
+    "ja-jp",
+    "se",
+    "se-fi",
+    "se-no",
+    "se-se",
+    "sv",
+    "sv-se",
+    "fi",
+    "fi-fi",
+    "zh",
+    "zh-cn",
+    "zh-tw",
+    "zh-hk",
+    "nl",
+    "nl-nl",
+    "be",
+    "be-by",
+    "pl",
+    "pl-pl",
+    "ru",
+    "ru-ru",
+    "af",
+    "bg",
+    "bg-bg",
+    "ua",
+    "uk",
+    "uk-ua",
+    "mk",
+    "mk-mk",
+    "de",
+    "de-de",
+    "de-ch",
+    "de-at",
+    "nb",
+    "nb-no",
+    "nn",
+    "nn-no",
+    "pt",
+    "pt-pt",
+    "pt-br",
+    "tl",
+    "tl-ph",
+    "vi",
+    "vi-vn",
+    "tr",
+    "tr-tr",
+    "az",
+    "az-az",
+    "da",
+    "da-dk",
+    "ml",
+    "hi",
+    "cs",
+    "cs-cz",
+    "sk",
+    "sk-sk",
+    "fa",
+    "fa-ir",
+    "mr",
+    "ca",
+    "ca-es",
+    "ca-ad",
+    "ca-fr",
+    "ca-it",
+    "eo",
+    "eo-xx",
+    "bn",
+    "bn-bd",
+    "bn-in",
+    "rm",
+    "rm-ch",
+    "ro",
+    "ro-ro",
+    "sl",
+    "sl-si",
+    "id",
+    "id-id",
+    "ne",
+    "ne-np",
+    "ee",
+    "et",
+    "sw",
+    "sw-ke",
+    "sw-tz",
+    "la",
+    "la-va",
+    "lt",
+    "lt-lt",
+    "ms",
+    "ms-my",
+    "ms-bn",
+    "or",
+    "or-in",
+    "lb",
+    "lb-lu",
+    "zu",
+    "zu-za",
+    "sq",
+    "sq-al",
+    "ta",
+    "ta-in",
+    "ta-lk",
+    "ur",
+    "ur-pk",
+    "ka",
+    "ka-ge",
+    "kk",
+    "kk-kz",
+    # "lo",
+    # "lo-la",
+    "am",
+    "am-et",
+    "hy-am",
+    "hy",
+    "uz",
+    "uz-uz",
+}

venv/Lib/site-packages/arrow/factory.py

@@ -0,0 +1,345 @@
+"""
+Implements the :class:`ArrowFactory <arrow.factory.ArrowFactory>` class,
+providing factory methods for common :class:`Arrow <arrow.arrow.Arrow>`
+construction scenarios.
+
+"""
+
+
+import calendar
+from datetime import date, datetime
+from datetime import tzinfo as dt_tzinfo
+from decimal import Decimal
+from time import struct_time
+from typing import Any, List, Optional, Tuple, Type, Union, overload
+
+from dateutil import tz as dateutil_tz
+
+from arrow import parser
+from arrow.arrow import TZ_EXPR, Arrow
+from arrow.constants import DEFAULT_LOCALE
+from arrow.util import is_timestamp, iso_to_gregorian
+
+
+class ArrowFactory:
+    """A factory for generating :class:`Arrow <arrow.arrow.Arrow>` objects.
+
+    :param type: (optional) the :class:`Arrow <arrow.arrow.Arrow>`-based class to construct from.
+        Defaults to :class:`Arrow <arrow.arrow.Arrow>`.
+
+    """
+
+    type: Type[Arrow]
+
+    def __init__(self, type: Type[Arrow] = Arrow) -> None:
+        self.type = type
+
+    @overload
+    def get(
+        self,
+        *,
+        locale: str = DEFAULT_LOCALE,
+        tzinfo: Optional[TZ_EXPR] = None,
+        normalize_whitespace: bool = False,
+    ) -> Arrow:
+        ...  # pragma: no cover
+
+    @overload
+    def get(
+        self,
+        __obj: Union[
+            Arrow,
+            datetime,
+            date,
+            struct_time,
+            dt_tzinfo,
+            int,
+            float,
+            str,
+            Tuple[int, int, int],
+        ],
+        *,
+        locale: str = DEFAULT_LOCALE,
+        tzinfo: Optional[TZ_EXPR] = None,
+        normalize_whitespace: bool = False,
+    ) -> Arrow:
+        ...  # pragma: no cover
+
+    @overload
+    def get(
+        self,
+        __arg1: Union[datetime, date],
+        __arg2: TZ_EXPR,
+        *,
+        locale: str = DEFAULT_LOCALE,
+        tzinfo: Optional[TZ_EXPR] = None,
+        normalize_whitespace: bool = False,
+    ) -> Arrow:
+        ...  # pragma: no cover
+
+    @overload
+    def get(
+        self,
+        __arg1: str,
+        __arg2: Union[str, List[str]],
+        *,
+        locale: str = DEFAULT_LOCALE,
+        tzinfo: Optional[TZ_EXPR] = None,
+        normalize_whitespace: bool = False,
+    ) -> Arrow:
+        ...  # pragma: no cover
+
+    def get(self, *args: Any, **kwargs: Any) -> Arrow:
+        """Returns an :class:`Arrow <arrow.arrow.Arrow>` object based on flexible inputs.
+
+        :param locale: (optional) a ``str`` specifying a locale for the parser. Defaults to 'en-us'.
+        :param tzinfo: (optional) a :ref:`timezone expression <tz-expr>` or tzinfo object.
+            Replaces the timezone unless using an input form that is explicitly UTC or specifies
+            the timezone in a positional argument. Defaults to UTC.
+        :param normalize_whitespace: (optional) a ``bool`` specifying whether or not to normalize
+            redundant whitespace (spaces, tabs, and newlines) in a datetime string before parsing.
+            Defaults to false.
+
+        Usage::
+
+            >>> import arrow
+
+        **No inputs** to get current UTC time::
+
+            >>> arrow.get()
+            <Arrow [2013-05-08T05:51:43.316458+00:00]>
+
+        **One** :class:`Arrow <arrow.arrow.Arrow>` object, to get a copy.
+
+            >>> arw = arrow.utcnow()
+            >>> arrow.get(arw)
+            <Arrow [2013-10-23T15:21:54.354846+00:00]>
+
+        **One** ``float`` or ``int``, convertible to a floating-point timestamp, to get
+        that timestamp in UTC::
+
+            >>> arrow.get(1367992474.293378)
+            <Arrow [2013-05-08T05:54:34.293378+00:00]>
+
+            >>> arrow.get(1367992474)
+            <Arrow [2013-05-08T05:54:34+00:00]>
+
+        **One** ISO 8601-formatted ``str``, to parse it::
+
+            >>> arrow.get('2013-09-29T01:26:43.830580')
+            <Arrow [2013-09-29T01:26:43.830580+00:00]>
+
+        **One** ISO 8601-formatted ``str``, in basic format, to parse it::
+
+            >>> arrow.get('20160413T133656.456289')
+            <Arrow [2016-04-13T13:36:56.456289+00:00]>
+
+        **One** ``tzinfo``, to get the current time **converted** to that timezone::
+
+            >>> arrow.get(tz.tzlocal())
+            <Arrow [2013-05-07T22:57:28.484717-07:00]>
+
+        **One** naive ``datetime``, to get that datetime in UTC::
+
+            >>> arrow.get(datetime(2013, 5, 5))
+            <Arrow [2013-05-05T00:00:00+00:00]>
+
+        **One** aware ``datetime``, to get that datetime::
+
+            >>> arrow.get(datetime(2013, 5, 5, tzinfo=tz.tzlocal()))
+            <Arrow [2013-05-05T00:00:00-07:00]>
+
+        **One** naive ``date``, to get that date in UTC::
+
+            >>> arrow.get(date(2013, 5, 5))
+            <Arrow [2013-05-05T00:00:00+00:00]>
+
+        **One** time.struct time::
+
+            >>> arrow.get(gmtime(0))
+            <Arrow [1970-01-01T00:00:00+00:00]>
+
+        **One** iso calendar ``tuple``, to get that week date in UTC::
+
+            >>> arrow.get((2013, 18, 7))
+            <Arrow [2013-05-05T00:00:00+00:00]>
+
+        **Two** arguments, a naive or aware ``datetime``, and a replacement
+        :ref:`timezone expression <tz-expr>`::
+
+            >>> arrow.get(datetime(2013, 5, 5), 'US/Pacific')
+            <Arrow [2013-05-05T00:00:00-07:00]>
+
+        **Two** arguments, a naive ``date``, and a replacement
+        :ref:`timezone expression <tz-expr>`::
+
+            >>> arrow.get(date(2013, 5, 5), 'US/Pacific')
+            <Arrow [2013-05-05T00:00:00-07:00]>
+
+        **Two** arguments, both ``str``, to parse the first according to the format of the second::
+
+            >>> arrow.get('2013-05-05 12:30:45 America/Chicago', 'YYYY-MM-DD HH:mm:ss ZZZ')
+            <Arrow [2013-05-05T12:30:45-05:00]>
+
+        **Two** arguments, first a ``str`` to parse and second a ``list`` of formats to try::
+
+            >>> arrow.get('2013-05-05 12:30:45', ['MM/DD/YYYY', 'YYYY-MM-DD HH:mm:ss'])
+            <Arrow [2013-05-05T12:30:45+00:00]>
+
+        **Three or more** arguments, as for the direct constructor of an ``Arrow`` object::
+
+            >>> arrow.get(2013, 5, 5, 12, 30, 45)
+            <Arrow [2013-05-05T12:30:45+00:00]>
+
+        """
+
+        arg_count = len(args)
+        locale = kwargs.pop("locale", DEFAULT_LOCALE)
+        tz = kwargs.get("tzinfo", None)
+        normalize_whitespace = kwargs.pop("normalize_whitespace", False)
+
+        # if kwargs given, send to constructor unless only tzinfo provided
+        if len(kwargs) > 1:
+            arg_count = 3
+
+        # tzinfo kwarg is not provided
+        if len(kwargs) == 1 and tz is None:
+            arg_count = 3
+
+        # () -> now, @ tzinfo or utc
+        if arg_count == 0:
+            if isinstance(tz, str):
+                tz = parser.TzinfoParser.parse(tz)
+                return self.type.now(tzinfo=tz)
+
+            if isinstance(tz, dt_tzinfo):
+                return self.type.now(tzinfo=tz)
+
+            return self.type.utcnow()
+
+        if arg_count == 1:
+            arg = args[0]
+            if isinstance(arg, Decimal):
+                arg = float(arg)
+
+            # (None) -> raises an exception
+            if arg is None:
+                raise TypeError("Cannot parse argument of type None.")
+
+            # try (int, float) -> from timestamp @ tzinfo
+            elif not isinstance(arg, str) and is_timestamp(arg):
+                if tz is None:
+                    # set to UTC by default
+                    tz = dateutil_tz.tzutc()
+                return self.type.fromtimestamp(arg, tzinfo=tz)
+
+            # (Arrow) -> from the object's datetime @ tzinfo
+            elif isinstance(arg, Arrow):
+                return self.type.fromdatetime(arg.datetime, tzinfo=tz)
+
+            # (datetime) -> from datetime @ tzinfo
+            elif isinstance(arg, datetime):
+                return self.type.fromdatetime(arg, tzinfo=tz)
+
+            # (date) -> from date @ tzinfo
+            elif isinstance(arg, date):
+                return self.type.fromdate(arg, tzinfo=tz)
+
+            # (tzinfo) -> now @ tzinfo
+            elif isinstance(arg, dt_tzinfo):
+                return self.type.now(tzinfo=arg)
+
+            # (str) -> parse @ tzinfo
+            elif isinstance(arg, str):
+                dt = parser.DateTimeParser(locale).parse_iso(arg, normalize_whitespace)
+                return self.type.fromdatetime(dt, tzinfo=tz)
+
+            # (struct_time) -> from struct_time
+            elif isinstance(arg, struct_time):
+                return self.type.utcfromtimestamp(calendar.timegm(arg))
+
+            # (iso calendar) -> convert then from date @ tzinfo
+            elif isinstance(arg, tuple) and len(arg) == 3:
+                d = iso_to_gregorian(*arg)
+                return self.type.fromdate(d, tzinfo=tz)
+
+            else:
+                raise TypeError(f"Cannot parse single argument of type {type(arg)!r}.")
+
+        elif arg_count == 2:
+            arg_1, arg_2 = args[0], args[1]
+
+            if isinstance(arg_1, datetime):
+                # (datetime, tzinfo/str) -> fromdatetime @ tzinfo
+                if isinstance(arg_2, (dt_tzinfo, str)):
+                    return self.type.fromdatetime(arg_1, tzinfo=arg_2)
+                else:
+                    raise TypeError(
+                        f"Cannot parse two arguments of types 'datetime', {type(arg_2)!r}."
+                    )
+
+            elif isinstance(arg_1, date):
+                # (date, tzinfo/str) -> fromdate @ tzinfo
+                if isinstance(arg_2, (dt_tzinfo, str)):
+                    return self.type.fromdate(arg_1, tzinfo=arg_2)
+                else:
+                    raise TypeError(
+                        f"Cannot parse two arguments of types 'date', {type(arg_2)!r}."
+                    )
+
+            # (str, format) -> parse @ tzinfo
+            elif isinstance(arg_1, str) and isinstance(arg_2, (str, list)):
+                dt = parser.DateTimeParser(locale).parse(
+                    args[0], args[1], normalize_whitespace
+                )
+                return self.type.fromdatetime(dt, tzinfo=tz)
+
+            else:
+                raise TypeError(
+                    f"Cannot parse two arguments of types {type(arg_1)!r} and {type(arg_2)!r}."
+                )
+
+        # 3+ args -> datetime-like via constructor
+        else:
+            return self.type(*args, **kwargs)
+
+    def utcnow(self) -> Arrow:
+        """Returns an :class:`Arrow <arrow.arrow.Arrow>` object, representing "now" in UTC time.
+
+        Usage::
+
+            >>> import arrow
+            >>> arrow.utcnow()
+            <Arrow [2013-05-08T05:19:07.018993+00:00]>
+        """
+
+        return self.type.utcnow()
+
+    def now(self, tz: Optional[TZ_EXPR] = None) -> Arrow:
+        """Returns an :class:`Arrow <arrow.arrow.Arrow>` object, representing "now" in the given
+        timezone.
+
+        :param tz: (optional) A :ref:`timezone expression <tz-expr>`.  Defaults to local time.
+
+        Usage::
+
+            >>> import arrow
+            >>> arrow.now()
+            <Arrow [2013-05-07T22:19:11.363410-07:00]>
+
+            >>> arrow.now('US/Pacific')
+            <Arrow [2013-05-07T22:19:15.251821-07:00]>
+
+            >>> arrow.now('+02:00')
+            <Arrow [2013-05-08T07:19:25.618646+02:00]>
+
+            >>> arrow.now('local')
+            <Arrow [2013-05-07T22:19:39.130059-07:00]>
+        """
+
+        if tz is None:
+            tz = dateutil_tz.tzlocal()
+        elif not isinstance(tz, dt_tzinfo):
+            tz = parser.TzinfoParser.parse(tz)
+
+        return self.type.now(tz)

venv/Lib/site-packages/arrow/formatter.py

@@ -0,0 +1,148 @@
+"""Provides the :class:`Arrow <arrow.formatter.DateTimeFormatter>` class, an improved formatter for datetimes."""
+
+import re
+import sys
+from datetime import datetime, timedelta
+from typing import Optional, Pattern, cast
+
+from dateutil import tz as dateutil_tz
+
+from arrow import locales
+from arrow.constants import DEFAULT_LOCALE
+
+if sys.version_info < (3, 8):  # pragma: no cover
+    from typing_extensions import Final
+else:
+    from typing import Final  # pragma: no cover
+
+
+FORMAT_ATOM: Final[str] = "YYYY-MM-DD HH:mm:ssZZ"
+FORMAT_COOKIE: Final[str] = "dddd, DD-MMM-YYYY HH:mm:ss ZZZ"
+FORMAT_RFC822: Final[str] = "ddd, DD MMM YY HH:mm:ss Z"
+FORMAT_RFC850: Final[str] = "dddd, DD-MMM-YY HH:mm:ss ZZZ"
+FORMAT_RFC1036: Final[str] = "ddd, DD MMM YY HH:mm:ss Z"
+FORMAT_RFC1123: Final[str] = "ddd, DD MMM YYYY HH:mm:ss Z"
+FORMAT_RFC2822: Final[str] = "ddd, DD MMM YYYY HH:mm:ss Z"
+FORMAT_RFC3339: Final[str] = "YYYY-MM-DD HH:mm:ssZZ"
+FORMAT_RSS: Final[str] = "ddd, DD MMM YYYY HH:mm:ss Z"
+FORMAT_W3C: Final[str] = "YYYY-MM-DD HH:mm:ssZZ"
+
+
+class DateTimeFormatter:
+    # This pattern matches characters enclosed in square brackets are matched as
+    # an atomic group. For more info on atomic groups and how to they are
+    # emulated in Python's re library, see https://stackoverflow.com/a/13577411/2701578
+
+    _FORMAT_RE: Final[Pattern[str]] = re.compile(
+        r"(\[(?:(?=(?P<literal>[^]]))(?P=literal))*\]|YYY?Y?|MM?M?M?|Do|DD?D?D?|d?dd?d?|HH?|hh?|mm?|ss?|SS?S?S?S?S?|ZZ?Z?|a|A|X|x|W)"
+    )
+
+    locale: locales.Locale
+
+    def __init__(self, locale: str = DEFAULT_LOCALE) -> None:
+        self.locale = locales.get_locale(locale)
+
+    def format(cls, dt: datetime, fmt: str) -> str:
+        # FIXME: _format_token() is nullable
+        return cls._FORMAT_RE.sub(
+            lambda m: cast(str, cls._format_token(dt, m.group(0))), fmt
+        )
+
+    def _format_token(self, dt: datetime, token: Optional[str]) -> Optional[str]:
+        if token and token.startswith("[") and token.endswith("]"):
+            return token[1:-1]
+
+        if token == "YYYY":
+            return self.locale.year_full(dt.year)
+        if token == "YY":
+            return self.locale.year_abbreviation(dt.year)
+
+        if token == "MMMM":
+            return self.locale.month_name(dt.month)
+        if token == "MMM":
+            return self.locale.month_abbreviation(dt.month)
+        if token == "MM":
+            return f"{dt.month:02d}"
+        if token == "M":
+            return f"{dt.month}"
+
+        if token == "DDDD":
+            return f"{dt.timetuple().tm_yday:03d}"
+        if token == "DDD":
+            return f"{dt.timetuple().tm_yday}"
+        if token == "DD":
+            return f"{dt.day:02d}"
+        if token == "D":
+            return f"{dt.day}"
+
+        if token == "Do":
+            return self.locale.ordinal_number(dt.day)
+
+        if token == "dddd":
+            return self.locale.day_name(dt.isoweekday())
+        if token == "ddd":
+            return self.locale.day_abbreviation(dt.isoweekday())
+        if token == "d":
+            return f"{dt.isoweekday()}"
+
+        if token == "HH":
+            return f"{dt.hour:02d}"
+        if token == "H":
+            return f"{dt.hour}"
+        if token == "hh":
+            return f"{dt.hour if 0 < dt.hour < 13 else abs(dt.hour - 12):02d}"
+        if token == "h":
+            return f"{dt.hour if 0 < dt.hour < 13 else abs(dt.hour - 12)}"
+
+        if token == "mm":
+            return f"{dt.minute:02d}"
+        if token == "m":
+            return f"{dt.minute}"
+
+        if token == "ss":
+            return f"{dt.second:02d}"
+        if token == "s":
+            return f"{dt.second}"
+
+        if token == "SSSSSS":
+            return f"{dt.microsecond:06d}"
+        if token == "SSSSS":
+            return f"{dt.microsecond // 10:05d}"
+        if token == "SSSS":
+            return f"{dt.microsecond // 100:04d}"
+        if token == "SSS":
+            return f"{dt.microsecond // 1000:03d}"
+        if token == "SS":
+            return f"{dt.microsecond // 10000:02d}"
+        if token == "S":
+            return f"{dt.microsecond // 100000}"
+
+        if token == "X":
+            return f"{dt.timestamp()}"
+
+        if token == "x":
+            return f"{dt.timestamp() * 1_000_000:.0f}"
+
+        if token == "ZZZ":
+            return dt.tzname()
+
+        if token in ["ZZ", "Z"]:
+            separator = ":" if token == "ZZ" else ""
+            tz = dateutil_tz.tzutc() if dt.tzinfo is None else dt.tzinfo
+            # `dt` must be aware object. Otherwise, this line will raise AttributeError
+            # https://github.com/arrow-py/arrow/pull/883#discussion_r529866834
+            # datetime awareness: https://docs.python.org/3/library/datetime.html#aware-and-naive-objects
+            total_minutes = int(cast(timedelta, tz.utcoffset(dt)).total_seconds() / 60)
+
+            sign = "+" if total_minutes >= 0 else "-"
+            total_minutes = abs(total_minutes)
+            hour, minute = divmod(total_minutes, 60)
+
+            return f"{sign}{hour:02d}{separator}{minute:02d}"
+
+        if token in ("a", "A"):
+            return self.locale.meridian(dt.hour, token)
+
+        if token == "W":
+            year, week, day = dt.isocalendar()
+            return f"{year}-W{week:02d}-{day}"

venv/Lib/site-packages/arrow/parser.py

@@ -0,0 +1,771 @@
+"""Provides the :class:`Arrow <arrow.parser.DateTimeParser>` class, a better way to parse datetime strings."""
+
+import re
+import sys
+from datetime import datetime, timedelta
+from datetime import tzinfo as dt_tzinfo
+from functools import lru_cache
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    Iterable,
+    List,
+    Match,
+    Optional,
+    Pattern,
+    SupportsFloat,
+    SupportsInt,
+    Tuple,
+    Union,
+    cast,
+    overload,
+)
+
+from dateutil import tz
+
+from arrow import locales
+from arrow.constants import DEFAULT_LOCALE
+from arrow.util import next_weekday, normalize_timestamp
+
+if sys.version_info < (3, 8):  # pragma: no cover
+    from typing_extensions import Literal, TypedDict
+else:
+    from typing import Literal, TypedDict  # pragma: no cover
+
+
+class ParserError(ValueError):
+    pass
+
+
+# Allows for ParserErrors to be propagated from _build_datetime()
+# when day_of_year errors occur.
+# Before this, the ParserErrors were caught by the try/except in
+# _parse_multiformat() and the appropriate error message was not
+# transmitted to the user.
+class ParserMatchError(ParserError):
+    pass
+
+
+_WEEKDATE_ELEMENT = Union[str, bytes, SupportsInt, bytearray]
+
+_FORMAT_TYPE = Literal[
+    "YYYY",
+    "YY",
+    "MM",
+    "M",
+    "DDDD",
+    "DDD",
+    "DD",
+    "D",
+    "HH",
+    "H",
+    "hh",
+    "h",
+    "mm",
+    "m",
+    "ss",
+    "s",
+    "X",
+    "x",
+    "ZZZ",
+    "ZZ",
+    "Z",
+    "S",
+    "W",
+    "MMMM",
+    "MMM",
+    "Do",
+    "dddd",
+    "ddd",
+    "d",
+    "a",
+    "A",
+]
+
+
+class _Parts(TypedDict, total=False):
+    year: int
+    month: int
+    day_of_year: int
+    day: int
+    hour: int
+    minute: int
+    second: int
+    microsecond: int
+    timestamp: float
+    expanded_timestamp: int
+    tzinfo: dt_tzinfo
+    am_pm: Literal["am", "pm"]
+    day_of_week: int
+    weekdate: Tuple[_WEEKDATE_ELEMENT, _WEEKDATE_ELEMENT, Optional[_WEEKDATE_ELEMENT]]
+
+
+class DateTimeParser:
+    _FORMAT_RE: ClassVar[Pattern[str]] = re.compile(
+        r"(YYY?Y?|MM?M?M?|Do|DD?D?D?|d?d?d?d|HH?|hh?|mm?|ss?|S+|ZZ?Z?|a|A|x|X|W)"
+    )
+    _ESCAPE_RE: ClassVar[Pattern[str]] = re.compile(r"\[[^\[\]]*\]")
+
+    _ONE_OR_TWO_DIGIT_RE: ClassVar[Pattern[str]] = re.compile(r"\d{1,2}")
+    _ONE_OR_TWO_OR_THREE_DIGIT_RE: ClassVar[Pattern[str]] = re.compile(r"\d{1,3}")
+    _ONE_OR_MORE_DIGIT_RE: ClassVar[Pattern[str]] = re.compile(r"\d+")
+    _TWO_DIGIT_RE: ClassVar[Pattern[str]] = re.compile(r"\d{2}")
+    _THREE_DIGIT_RE: ClassVar[Pattern[str]] = re.compile(r"\d{3}")
+    _FOUR_DIGIT_RE: ClassVar[Pattern[str]] = re.compile(r"\d{4}")
+    _TZ_Z_RE: ClassVar[Pattern[str]] = re.compile(r"([\+\-])(\d{2})(?:(\d{2}))?|Z")
+    _TZ_ZZ_RE: ClassVar[Pattern[str]] = re.compile(r"([\+\-])(\d{2})(?:\:(\d{2}))?|Z")
+    _TZ_NAME_RE: ClassVar[Pattern[str]] = re.compile(r"\w[\w+\-/]+")
+    # NOTE: timestamps cannot be parsed from natural language strings (by removing the ^...$) because it will
+    # break cases like "15 Jul 2000" and a format list (see issue #447)
+    _TIMESTAMP_RE: ClassVar[Pattern[str]] = re.compile(r"^\-?\d+\.?\d+$")
+    _TIMESTAMP_EXPANDED_RE: ClassVar[Pattern[str]] = re.compile(r"^\-?\d+$")
+    _TIME_RE: ClassVar[Pattern[str]] = re.compile(
+        r"^(\d{2})(?:\:?(\d{2}))?(?:\:?(\d{2}))?(?:([\.\,])(\d+))?$"
+    )
+    _WEEK_DATE_RE: ClassVar[Pattern[str]] = re.compile(
+        r"(?P<year>\d{4})[\-]?W(?P<week>\d{2})[\-]?(?P<day>\d)?"
+    )
+
+    _BASE_INPUT_RE_MAP: ClassVar[Dict[_FORMAT_TYPE, Pattern[str]]] = {
+        "YYYY": _FOUR_DIGIT_RE,
+        "YY": _TWO_DIGIT_RE,
+        "MM": _TWO_DIGIT_RE,
+        "M": _ONE_OR_TWO_DIGIT_RE,
+        "DDDD": _THREE_DIGIT_RE,
+        "DDD": _ONE_OR_TWO_OR_THREE_DIGIT_RE,
+        "DD": _TWO_DIGIT_RE,
+        "D": _ONE_OR_TWO_DIGIT_RE,
+        "HH": _TWO_DIGIT_RE,
+        "H": _ONE_OR_TWO_DIGIT_RE,
+        "hh": _TWO_DIGIT_RE,
+        "h": _ONE_OR_TWO_DIGIT_RE,
+        "mm": _TWO_DIGIT_RE,
+        "m": _ONE_OR_TWO_DIGIT_RE,
+        "ss": _TWO_DIGIT_RE,
+        "s": _ONE_OR_TWO_DIGIT_RE,
+        "X": _TIMESTAMP_RE,
+        "x": _TIMESTAMP_EXPANDED_RE,
+        "ZZZ": _TZ_NAME_RE,
+        "ZZ": _TZ_ZZ_RE,
+        "Z": _TZ_Z_RE,
+        "S": _ONE_OR_MORE_DIGIT_RE,
+        "W": _WEEK_DATE_RE,
+    }
+
+    SEPARATORS: ClassVar[List[str]] = ["-", "/", "."]
+
+    locale: locales.Locale
+    _input_re_map: Dict[_FORMAT_TYPE, Pattern[str]]
+
+    def __init__(self, locale: str = DEFAULT_LOCALE, cache_size: int = 0) -> None:
+        self.locale = locales.get_locale(locale)
+        self._input_re_map = self._BASE_INPUT_RE_MAP.copy()
+        self._input_re_map.update(
+            {
+                "MMMM": self._generate_choice_re(
+                    self.locale.month_names[1:], re.IGNORECASE
+                ),
+                "MMM": self._generate_choice_re(
+                    self.locale.month_abbreviations[1:], re.IGNORECASE
+                ),
+                "Do": re.compile(self.locale.ordinal_day_re),
+                "dddd": self._generate_choice_re(
+                    self.locale.day_names[1:], re.IGNORECASE
+                ),
+                "ddd": self._generate_choice_re(
+                    self.locale.day_abbreviations[1:], re.IGNORECASE
+                ),
+                "d": re.compile(r"[1-7]"),
+                "a": self._generate_choice_re(
+                    (self.locale.meridians["am"], self.locale.meridians["pm"])
+                ),
+                # note: 'A' token accepts both 'am/pm' and 'AM/PM' formats to
+                # ensure backwards compatibility of this token
+                "A": self._generate_choice_re(self.locale.meridians.values()),
+            }
+        )
+        if cache_size > 0:
+            self._generate_pattern_re = lru_cache(maxsize=cache_size)(  # type: ignore
+                self._generate_pattern_re
+            )
+
+    # TODO: since we support more than ISO 8601, we should rename this function
+    # IDEA: break into multiple functions
+    def parse_iso(
+        self, datetime_string: str, normalize_whitespace: bool = False
+    ) -> datetime:
+        if normalize_whitespace:
+            datetime_string = re.sub(r"\s+", " ", datetime_string.strip())
+
+        has_space_divider = " " in datetime_string
+        has_t_divider = "T" in datetime_string
+
+        num_spaces = datetime_string.count(" ")
+        if has_space_divider and num_spaces != 1 or has_t_divider and num_spaces > 0:
+            raise ParserError(
+                f"Expected an ISO 8601-like string, but was given {datetime_string!r}. "
+                "Try passing in a format string to resolve this."
+            )
+
+        has_time = has_space_divider or has_t_divider
+        has_tz = False
+
+        # date formats (ISO 8601 and others) to test against
+        # NOTE: YYYYMM is omitted to avoid confusion with YYMMDD (no longer part of ISO 8601, but is still often used)
+        formats = [
+            "YYYY-MM-DD",
+            "YYYY-M-DD",
+            "YYYY-M-D",
+            "YYYY/MM/DD",
+            "YYYY/M/DD",
+            "YYYY/M/D",
+            "YYYY.MM.DD",
+            "YYYY.M.DD",
+            "YYYY.M.D",
+            "YYYYMMDD",
+            "YYYY-DDDD",
+            "YYYYDDDD",
+            "YYYY-MM",
+            "YYYY/MM",
+            "YYYY.MM",
+            "YYYY",
+            "W",
+        ]
+
+        if has_time:
+            if has_space_divider:
+                date_string, time_string = datetime_string.split(" ", 1)
+            else:
+                date_string, time_string = datetime_string.split("T", 1)
+
+            time_parts = re.split(
+                r"[\+\-Z]", time_string, maxsplit=1, flags=re.IGNORECASE
+            )
+
+            time_components: Optional[Match[str]] = self._TIME_RE.match(time_parts[0])
+
+            if time_components is None:
+                raise ParserError(
+                    "Invalid time component provided. "
+                    "Please specify a format or provide a valid time component in the basic or extended ISO 8601 time format."
+                )
+
+            (
+                hours,
+                minutes,
+                seconds,
+                subseconds_sep,
+                subseconds,
+            ) = time_components.groups()
+
+            has_tz = len(time_parts) == 2
+            has_minutes = minutes is not None
+            has_seconds = seconds is not None
+            has_subseconds = subseconds is not None
+
+            is_basic_time_format = ":" not in time_parts[0]
+            tz_format = "Z"
+
+            # use 'ZZ' token instead since tz offset is present in non-basic format
+            if has_tz and ":" in time_parts[1]:
+                tz_format = "ZZ"
+
+            time_sep = "" if is_basic_time_format else ":"
+
+            if has_subseconds:
+                time_string = "HH{time_sep}mm{time_sep}ss{subseconds_sep}S".format(
+                    time_sep=time_sep, subseconds_sep=subseconds_sep
+                )
+            elif has_seconds:
+                time_string = "HH{time_sep}mm{time_sep}ss".format(time_sep=time_sep)
+            elif has_minutes:
+                time_string = f"HH{time_sep}mm"
+            else:
+                time_string = "HH"
+
+            if has_space_divider:
+                formats = [f"{f} {time_string}" for f in formats]
+            else:
+                formats = [f"{f}T{time_string}" for f in formats]
+
+        if has_time and has_tz:
+            # Add "Z" or "ZZ" to the format strings to indicate to
+            # _parse_token() that a timezone needs to be parsed
+            formats = [f"{f}{tz_format}" for f in formats]
+
+        return self._parse_multiformat(datetime_string, formats)
+
+    def parse(
+        self,
+        datetime_string: str,
+        fmt: Union[List[str], str],
+        normalize_whitespace: bool = False,
+    ) -> datetime:
+        if normalize_whitespace:
+            datetime_string = re.sub(r"\s+", " ", datetime_string)
+
+        if isinstance(fmt, list):
+            return self._parse_multiformat(datetime_string, fmt)
+
+        try:
+            fmt_tokens: List[_FORMAT_TYPE]
+            fmt_pattern_re: Pattern[str]
+            fmt_tokens, fmt_pattern_re = self._generate_pattern_re(fmt)
+        except re.error as e:
+            raise ParserMatchError(
+                f"Failed to generate regular expression pattern: {e}."
+            )
+
+        match = fmt_pattern_re.search(datetime_string)
+
+        if match is None:
+            raise ParserMatchError(
+                f"Failed to match {fmt!r} when parsing {datetime_string!r}."
+            )
+
+        parts: _Parts = {}
+        for token in fmt_tokens:
+            value: Union[Tuple[str, str, str], str]
+            if token == "Do":
+                value = match.group("value")
+            elif token == "W":
+                value = (match.group("year"), match.group("week"), match.group("day"))
+            else:
+                value = match.group(token)
+
+            if value is None:
+                raise ParserMatchError(
+                    f"Unable to find a match group for the specified token {token!r}."
+                )
+
+            self._parse_token(token, value, parts)  # type: ignore[arg-type]
+
+        return self._build_datetime(parts)
+
+    def _generate_pattern_re(self, fmt: str) -> Tuple[List[_FORMAT_TYPE], Pattern[str]]:
+        # fmt is a string of tokens like 'YYYY-MM-DD'
+        # we construct a new string by replacing each
+        # token by its pattern:
+        # 'YYYY-MM-DD' -> '(?P<YYYY>\d{4})-(?P<MM>\d{2})-(?P<DD>\d{2})'
+        tokens: List[_FORMAT_TYPE] = []
+        offset = 0
+
+        # Escape all special RegEx chars
+        escaped_fmt = re.escape(fmt)
+
+        # Extract the bracketed expressions to be reinserted later.
+        escaped_fmt = re.sub(self._ESCAPE_RE, "#", escaped_fmt)
+
+        # Any number of S is the same as one.
+        # TODO: allow users to specify the number of digits to parse
+        escaped_fmt = re.sub(r"S+", "S", escaped_fmt)
+
+        escaped_data = re.findall(self._ESCAPE_RE, fmt)
+
+        fmt_pattern = escaped_fmt
+
+        for m in self._FORMAT_RE.finditer(escaped_fmt):
+            token: _FORMAT_TYPE = cast(_FORMAT_TYPE, m.group(0))
+            try:
+                input_re = self._input_re_map[token]
+            except KeyError:
+                raise ParserError(f"Unrecognized token {token!r}.")
+            input_pattern = f"(?P<{token}>{input_re.pattern})"
+            tokens.append(token)
+            # a pattern doesn't have the same length as the token
+            # it replaces! We keep the difference in the offset variable.
+            # This works because the string is scanned left-to-right and matches
+            # are returned in the order found by finditer.
+            fmt_pattern = (
+                fmt_pattern[: m.start() + offset]
+                + input_pattern
+                + fmt_pattern[m.end() + offset :]
+            )
+            offset += len(input_pattern) - (m.end() - m.start())
+
+        final_fmt_pattern = ""
+        split_fmt = fmt_pattern.split(r"\#")
+
+        # Due to the way Python splits, 'split_fmt' will always be longer
+        for i in range(len(split_fmt)):
+            final_fmt_pattern += split_fmt[i]
+            if i < len(escaped_data):
+                final_fmt_pattern += escaped_data[i][1:-1]
+
+        # Wrap final_fmt_pattern in a custom word boundary to strictly
+        # match the formatting pattern and filter out date and time formats
+        # that include junk such as: blah1998-09-12 blah, blah 1998-09-12blah,
+        # blah1998-09-12blah. The custom word boundary matches every character
+        # that is not a whitespace character to allow for searching for a date
+        # and time string in a natural language sentence. Therefore, searching
+        # for a string of the form YYYY-MM-DD in "blah 1998-09-12 blah" will
+        # work properly.
+        # Certain punctuation before or after the target pattern such as
+        # "1998-09-12," is permitted. For the full list of valid punctuation,
+        # see the documentation.
+
+        starting_word_boundary = (
+            r"(?<!\S\S)"  # Don't have two consecutive non-whitespace characters. This ensures that we allow cases
+            # like .11.25.2019 but not 1.11.25.2019 (for pattern MM.DD.YYYY)
+            r"(?<![^\,\.\;\:\?\!\"\'\`\[\]\{\}\(\)<>\s])"  # This is the list of punctuation that is ok before the
+            # pattern (i.e. "It can't not be these characters before the pattern")
+            r"(\b|^)"
+            # The \b is to block cases like 1201912 but allow 201912 for pattern YYYYMM. The ^ was necessary to allow a
+            # negative number through i.e. before epoch numbers
+        )
+        ending_word_boundary = (
+            r"(?=[\,\.\;\:\?\!\"\'\`\[\]\{\}\(\)\<\>]?"  # Positive lookahead stating that these punctuation marks
+            # can appear after the pattern at most 1 time
+            r"(?!\S))"  # Don't allow any non-whitespace character after the punctuation
+        )
+        bounded_fmt_pattern = r"{}{}{}".format(
+            starting_word_boundary, final_fmt_pattern, ending_word_boundary
+        )
+
+        return tokens, re.compile(bounded_fmt_pattern, flags=re.IGNORECASE)
+
+    @overload
+    def _parse_token(
+        self,
+        token: Literal[
+            "YYYY",
+            "YY",
+            "MM",
+            "M",
+            "DDDD",
+            "DDD",
+            "DD",
+            "D",
+            "Do",
+            "HH",
+            "hh",
+            "h",
+            "H",
+            "mm",
+            "m",
+            "ss",
+            "s",
+            "x",
+        ],
+        value: Union[str, bytes, SupportsInt, bytearray],
+        parts: _Parts,
+    ) -> None:
+        ...  # pragma: no cover
+
+    @overload
+    def _parse_token(
+        self,
+        token: Literal["X"],
+        value: Union[str, bytes, SupportsFloat, bytearray],
+        parts: _Parts,
+    ) -> None:
+        ...  # pragma: no cover
+
+    @overload
+    def _parse_token(
+        self,
+        token: Literal["MMMM", "MMM", "dddd", "ddd", "S"],
+        value: Union[str, bytes, bytearray],
+        parts: _Parts,
+    ) -> None:
+        ...  # pragma: no cover
+
+    @overload
+    def _parse_token(
+        self,
+        token: Literal["a", "A", "ZZZ", "ZZ", "Z"],
+        value: Union[str, bytes],
+        parts: _Parts,
+    ) -> None:
+        ...  # pragma: no cover
+
+    @overload
+    def _parse_token(
+        self,
+        token: Literal["W"],
+        value: Tuple[_WEEKDATE_ELEMENT, _WEEKDATE_ELEMENT, Optional[_WEEKDATE_ELEMENT]],
+        parts: _Parts,
+    ) -> None:
+        ...  # pragma: no cover
+
+    def _parse_token(
+        self,
+        token: Any,
+        value: Any,
+        parts: _Parts,
+    ) -> None:
+        if token == "YYYY":
+            parts["year"] = int(value)
+
+        elif token == "YY":
+            value = int(value)
+            parts["year"] = 1900 + value if value > 68 else 2000 + value
+
+        elif token in ["MMMM", "MMM"]:
+            # FIXME: month_number() is nullable
+            parts["month"] = self.locale.month_number(value.lower())  # type: ignore[typeddict-item]
+
+        elif token in ["MM", "M"]:
+            parts["month"] = int(value)
+
+        elif token in ["DDDD", "DDD"]:
+            parts["day_of_year"] = int(value)
+
+        elif token in ["DD", "D"]:
+            parts["day"] = int(value)
+
+        elif token == "Do":
+            parts["day"] = int(value)
+
+        elif token == "dddd":
+            # locale day names are 1-indexed
+            day_of_week = [x.lower() for x in self.locale.day_names].index(
+                value.lower()
+            )
+            parts["day_of_week"] = day_of_week - 1
+
+        elif token == "ddd":
+            # locale day abbreviations are 1-indexed
+            day_of_week = [x.lower() for x in self.locale.day_abbreviations].index(
+                value.lower()
+            )
+            parts["day_of_week"] = day_of_week - 1
+
+        elif token.upper() in ["HH", "H"]:
+            parts["hour"] = int(value)
+
+        elif token in ["mm", "m"]:
+            parts["minute"] = int(value)
+
+        elif token in ["ss", "s"]:
+            parts["second"] = int(value)
+
+        elif token == "S":
+            # We have the *most significant* digits of an arbitrary-precision integer.
+            # We want the six most significant digits as an integer, rounded.
+            # IDEA: add nanosecond support somehow? Need datetime support for it first.
+            value = value.ljust(7, "0")
+
+            # floating-point (IEEE-754) defaults to half-to-even rounding
+            seventh_digit = int(value[6])
+            if seventh_digit == 5:
+                rounding = int(value[5]) % 2
+            elif seventh_digit > 5:
+                rounding = 1
+            else:
+                rounding = 0
+
+            parts["microsecond"] = int(value[:6]) + rounding
+
+        elif token == "X":
+            parts["timestamp"] = float(value)
+
+        elif token == "x":
+            parts["expanded_timestamp"] = int(value)
+
+        elif token in ["ZZZ", "ZZ", "Z"]:
+            parts["tzinfo"] = TzinfoParser.parse(value)
+
+        elif token in ["a", "A"]:
+            if value in (self.locale.meridians["am"], self.locale.meridians["AM"]):
+                parts["am_pm"] = "am"
+                if "hour" in parts and not 0 <= parts["hour"] <= 12:
+                    raise ParserMatchError(
+                        f"Hour token value must be between 0 and 12 inclusive for token {token!r}."
+                    )
+            elif value in (self.locale.meridians["pm"], self.locale.meridians["PM"]):
+                parts["am_pm"] = "pm"
+        elif token == "W":
+            parts["weekdate"] = value
+
+    @staticmethod
+    def _build_datetime(parts: _Parts) -> datetime:
+        weekdate = parts.get("weekdate")
+
+        if weekdate is not None:
+            year, week = int(weekdate[0]), int(weekdate[1])
+
+            if weekdate[2] is not None:
+                _day = int(weekdate[2])
+            else:
+                # day not given, default to 1
+                _day = 1
+
+            date_string = f"{year}-{week}-{_day}"
+
+            #  tokens for ISO 8601 weekdates
+            dt = datetime.strptime(date_string, "%G-%V-%u")
+
+            parts["year"] = dt.year
+            parts["month"] = dt.month
+            parts["day"] = dt.day
+
+        timestamp = parts.get("timestamp")
+
+        if timestamp is not None:
+            return datetime.fromtimestamp(timestamp, tz=tz.tzutc())
+
+        expanded_timestamp = parts.get("expanded_timestamp")
+
+        if expanded_timestamp is not None:
+            return datetime.fromtimestamp(
+                normalize_timestamp(expanded_timestamp),
+                tz=tz.tzutc(),
+            )
+
+        day_of_year = parts.get("day_of_year")
+
+        if day_of_year is not None:
+            _year = parts.get("year")
+            month = parts.get("month")
+            if _year is None:
+                raise ParserError(
+                    "Year component is required with the DDD and DDDD tokens."
+                )
+
+            if month is not None:
+                raise ParserError(
+                    "Month component is not allowed with the DDD and DDDD tokens."
+                )
+
+            date_string = f"{_year}-{day_of_year}"
+            try:
+                dt = datetime.strptime(date_string, "%Y-%j")
+            except ValueError:
+                raise ParserError(
+                    f"The provided day of year {day_of_year!r} is invalid."
+                )
+
+            parts["year"] = dt.year
+            parts["month"] = dt.month
+            parts["day"] = dt.day
+
+        day_of_week: Optional[int] = parts.get("day_of_week")
+        day = parts.get("day")
+
+        # If day is passed, ignore day of week
+        if day_of_week is not None and day is None:
+            year = parts.get("year", 1970)
+            month = parts.get("month", 1)
+            day = 1
+
+            # dddd => first day of week after epoch
+            # dddd YYYY => first day of week in specified year
+            # dddd MM YYYY => first day of week in specified year and month
+            # dddd MM => first day after epoch in specified month
+            next_weekday_dt = next_weekday(datetime(year, month, day), day_of_week)
+            parts["year"] = next_weekday_dt.year
+            parts["month"] = next_weekday_dt.month
+            parts["day"] = next_weekday_dt.day
+
+        am_pm = parts.get("am_pm")
+        hour = parts.get("hour", 0)
+
+        if am_pm == "pm" and hour < 12:
+            hour += 12
+        elif am_pm == "am" and hour == 12:
+            hour = 0
+
+        # Support for midnight at the end of day
+        if hour == 24:
+            if parts.get("minute", 0) != 0:
+                raise ParserError("Midnight at the end of day must not contain minutes")
+            if parts.get("second", 0) != 0:
+                raise ParserError("Midnight at the end of day must not contain seconds")
+            if parts.get("microsecond", 0) != 0:
+                raise ParserError(
+                    "Midnight at the end of day must not contain microseconds"
+                )
+            hour = 0
+            day_increment = 1
+        else:
+            day_increment = 0
+
+        # account for rounding up to 1000000
+        microsecond = parts.get("microsecond", 0)
+        if microsecond == 1000000:
+            microsecond = 0
+            second_increment = 1
+        else:
+            second_increment = 0
+
+        increment = timedelta(days=day_increment, seconds=second_increment)
+
+        return (
+            datetime(
+                year=parts.get("year", 1),
+                month=parts.get("month", 1),
+                day=parts.get("day", 1),
+                hour=hour,
+                minute=parts.get("minute", 0),
+                second=parts.get("second", 0),
+                microsecond=microsecond,
+                tzinfo=parts.get("tzinfo"),
+            )
+            + increment
+        )
+
+    def _parse_multiformat(self, string: str, formats: Iterable[str]) -> datetime:
+        _datetime: Optional[datetime] = None
+
+        for fmt in formats:
+            try:
+                _datetime = self.parse(string, fmt)
+                break
+            except ParserMatchError:
+                pass
+
+        if _datetime is None:
+            supported_formats = ", ".join(formats)
+            raise ParserError(
+                f"Could not match input {string!r} to any of the following formats: {supported_formats}."
+            )
+
+        return _datetime
+
+    # generates a capture group of choices separated by an OR operator
+    @staticmethod
+    def _generate_choice_re(
+        choices: Iterable[str], flags: Union[int, re.RegexFlag] = 0
+    ) -> Pattern[str]:
+        return re.compile(r"({})".format("|".join(choices)), flags=flags)
+
+
+class TzinfoParser:
+    _TZINFO_RE: ClassVar[Pattern[str]] = re.compile(
+        r"^(?:\(UTC)*([\+\-])?(\d{2})(?:\:?(\d{2}))?"
+    )
+
+    @classmethod
+    def parse(cls, tzinfo_string: str) -> dt_tzinfo:
+        tzinfo: Optional[dt_tzinfo] = None
+
+        if tzinfo_string == "local":
+            tzinfo = tz.tzlocal()
+
+        elif tzinfo_string in ["utc", "UTC", "Z"]:
+            tzinfo = tz.tzutc()
+
+        else:
+            iso_match = cls._TZINFO_RE.match(tzinfo_string)
+
+            if iso_match:
+                sign: Optional[str]
+                hours: str
+                minutes: Union[str, int, None]
+                sign, hours, minutes = iso_match.groups()
+                seconds = int(hours) * 3600 + int(minutes or 0) * 60
+
+                if sign == "-":
+                    seconds *= -1
+
+                tzinfo = tz.tzoffset(None, seconds)
+
+            else:
+                tzinfo = tz.gettz(tzinfo_string)
+
+        if tzinfo is None:
+            raise ParserError(f"Could not parse timezone expression {tzinfo_string!r}.")
+
+        return tzinfo

venv/Lib/site-packages/arrow/util.py

@@ -0,0 +1,117 @@
+"""Helpful functions used internally within arrow."""
+
+import datetime
+from typing import Any, Optional, cast
+
+from dateutil.rrule import WEEKLY, rrule
+
+from arrow.constants import (
+    MAX_ORDINAL,
+    MAX_TIMESTAMP,
+    MAX_TIMESTAMP_MS,
+    MAX_TIMESTAMP_US,
+    MIN_ORDINAL,
+)
+
+
+def next_weekday(
+    start_date: Optional[datetime.date], weekday: int
+) -> datetime.datetime:
+    """Get next weekday from the specified start date.
+
+    :param start_date: Datetime object representing the start date.
+    :param weekday: Next weekday to obtain. Can be a value between 0 (Monday) and 6 (Sunday).
+    :return: Datetime object corresponding to the next weekday after start_date.
+
+    Usage::
+
+        # Get first Monday after epoch
+        >>> next_weekday(datetime(1970, 1, 1), 0)
+        1970-01-05 00:00:00
+
+        # Get first Thursday after epoch
+        >>> next_weekday(datetime(1970, 1, 1), 3)
+        1970-01-01 00:00:00
+
+        # Get first Sunday after epoch
+        >>> next_weekday(datetime(1970, 1, 1), 6)
+        1970-01-04 00:00:00
+    """
+    if weekday < 0 or weekday > 6:
+        raise ValueError("Weekday must be between 0 (Monday) and 6 (Sunday).")
+    return cast(
+        datetime.datetime,
+        rrule(freq=WEEKLY, dtstart=start_date, byweekday=weekday, count=1)[0],
+    )
+
+
+def is_timestamp(value: Any) -> bool:
+    """Check if value is a valid timestamp."""
+    if isinstance(value, bool):
+        return False
+    if not isinstance(value, (int, float, str)):
+        return False
+    try:
+        float(value)
+        return True
+    except ValueError:
+        return False
+
+
+def validate_ordinal(value: Any) -> None:
+    """Raise an exception if value is an invalid Gregorian ordinal.
+
+    :param value: the input to be checked
+
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"Ordinal must be an integer (got type {type(value)}).")
+    if not (MIN_ORDINAL <= value <= MAX_ORDINAL):
+        raise ValueError(f"Ordinal {value} is out of range.")
+
+
+def normalize_timestamp(timestamp: float) -> float:
+    """Normalize millisecond and microsecond timestamps into normal timestamps."""
+    if timestamp > MAX_TIMESTAMP:
+        if timestamp < MAX_TIMESTAMP_MS:
+            timestamp /= 1000
+        elif timestamp < MAX_TIMESTAMP_US:
+            timestamp /= 1_000_000
+        else:
+            raise ValueError(f"The specified timestamp {timestamp!r} is too large.")
+    return timestamp
+
+
+# Credit to https://stackoverflow.com/a/1700069
+def iso_to_gregorian(iso_year: int, iso_week: int, iso_day: int) -> datetime.date:
+    """Converts an ISO week date into a datetime object.
+
+    :param iso_year: the year
+    :param iso_week: the week number, each year has either 52 or 53 weeks
+    :param iso_day: the day numbered 1 through 7, beginning with Monday
+
+    """
+
+    if not 1 <= iso_week <= 53:
+        raise ValueError("ISO Calendar week value must be between 1-53.")
+
+    if not 1 <= iso_day <= 7:
+        raise ValueError("ISO Calendar day value must be between 1-7")
+
+    # The first week of the year always contains 4 Jan.
+    fourth_jan = datetime.date(iso_year, 1, 4)
+    delta = datetime.timedelta(fourth_jan.isoweekday() - 1)
+    year_start = fourth_jan - delta
+    gregorian = year_start + datetime.timedelta(days=iso_day - 1, weeks=iso_week - 1)
+
+    return gregorian
+
+
+def validate_bounds(bounds: str) -> None:
+    if bounds != "()" and bounds != "(]" and bounds != "[)" and bounds != "[]":
+        raise ValueError(
+            "Invalid bounds. Please select between '()', '(]', '[)', or '[]'."
+        )
+
+
+__all__ = ["next_weekday", "is_timestamp", "validate_ordinal", "iso_to_gregorian"]

venv/Lib/site-packages/asttokens-3.0.0.dist-info/INSTALLER

@@ -0,0 +1 @@
+pip

venv/Lib/site-packages/asttokens-3.0.0.dist-info/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

venv/Lib/site-packages/asttokens-3.0.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.1
+Name: asttokens
+Version: 3.0.0
+Summary: Annotate AST trees with source code positions
+Home-page: https://github.com/gristlabs/asttokens
+Author: Dmitry Sagalovskiy, Grist Labs
+Author-email: [email protected]
+License: Apache 2.0
+Keywords: code,ast,parse,tokenize,refactor
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Software Development :: Pre-processors
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+License-File: LICENSE
+Provides-Extra: astroid
+Requires-Dist: astroid<4,>=2; extra == "astroid"
+Provides-Extra: test
+Requires-Dist: astroid<4,>=2; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+
+ASTTokens
+=========
+
+.. image:: https://img.shields.io/pypi/v/asttokens.svg
+    :target: https://pypi.python.org/pypi/asttokens/
+.. image:: https://img.shields.io/pypi/pyversions/asttokens.svg
+    :target: https://pypi.python.org/pypi/asttokens/
+.. image:: https://github.com/gristlabs/asttokens/actions/workflows/build-and-test.yml/badge.svg
+    :target: https://github.com/gristlabs/asttokens/actions/workflows/build-and-test.yml
+.. image:: https://readthedocs.org/projects/asttokens/badge/?version=latest
+    :target: http://asttokens.readthedocs.io/en/latest/index.html
+.. image:: https://coveralls.io/repos/github/gristlabs/asttokens/badge.svg
+    :target: https://coveralls.io/github/gristlabs/asttokens
+
+.. Start of user-guide
+
+The ``asttokens`` module annotates Python abstract syntax trees (ASTs) with the positions of tokens
+and text in the source code that generated them.
+
+It makes it possible for tools that work with logical AST nodes to find the particular text that
+resulted in those nodes, for example for automated refactoring or highlighting.
+
+Installation
+------------
+asttokens is available on PyPI: https://pypi.python.org/pypi/asttokens/::
+
+    pip install asttokens
+
+The code is on GitHub: https://github.com/gristlabs/asttokens.
+
+The API Reference is here: http://asttokens.readthedocs.io/en/latest/api-index.html.
+
+Usage
+-----
+
+ASTTokens can annotate both trees built by `ast <https://docs.python.org/2/library/ast.html>`_,
+AND those built by `astroid <https://github.com/PyCQA/astroid>`_.
+
+Here's an example:
+
+.. code-block:: python
+
+    import asttokens, ast
+    source = "Robot('blue').walk(steps=10*n)"
+    atok = asttokens.ASTTokens(source, parse=True)
+
+Once the tree has been marked, nodes get ``.first_token``, ``.last_token`` attributes, and
+the ``ASTTokens`` object offers helpful methods:
+
+.. code-block:: python
+
+    attr_node = next(n for n in ast.walk(atok.tree) if isinstance(n, ast.Attribute))
+    print(atok.get_text(attr_node))
+    start, end = attr_node.last_token.startpos, attr_node.last_token.endpos
+    print(atok.text[:start] + 'RUN' + atok.text[end:])
+
+Which produces this output:
+
+.. code-block:: text
+
+    Robot('blue').walk
+    Robot('blue').RUN(steps=10*n)
+
+The ``ASTTokens`` object also offers methods to walk and search the list of tokens that make up
+the code (or a particular AST node), which is more useful and powerful than dealing with the text
+directly.
+
+
+Contribute
+----------
+
+To contribute:
+
+1. Fork this repository, and clone your fork.
+2. Install the package with test dependencies (ideally in a virtualenv) with::
+
+    pip install -e '.[test]'
+
+3. Run tests in your current interpreter with the command ``pytest`` or ``python -m pytest``.
+4. Run tests across all supported interpreters with the ``tox`` command. You will need to have the interpreters installed separately. We recommend ``pyenv`` for that. Use ``tox -p auto`` to run the tests in parallel.
+5. By default certain tests which take a very long time to run are skipped, but they are run in CI.
+   These are marked using the ``pytest`` marker ``slow`` and can be run on their own with ``pytest -m slow`` or as part of the full suite with ``pytest -m ''``.

venv/Lib/site-packages/asttokens-3.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+asttokens-3.0.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+asttokens-3.0.0.dist-info/LICENSE,sha256=tAkwu8-AdEyGxGoSvJ2gVmQdcicWw3j1ZZueVV74M-E,11357
+asttokens-3.0.0.dist-info/METADATA,sha256=cg1yWNJgO6xzqQzaKsQoKJuKZMEfuJAh07iQLAgNv6k,4726
+asttokens-3.0.0.dist-info/RECORD,,
+asttokens-3.0.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+asttokens-3.0.0.dist-info/top_level.txt,sha256=nJDweSD7_NBhOlR3c8bkKJMKM-pxlAS8Kyh8GcCT2dk,10
+asttokens/__init__.py,sha256=8eONA3X-9s93-v-2gEoz4649fDUpvzBthFB5Ld7dHAg,962
+asttokens/__pycache__/__init__.cpython-312.pyc,,
+asttokens/__pycache__/astroid_compat.cpython-312.pyc,,
+asttokens/__pycache__/asttokens.cpython-312.pyc,,
+asttokens/__pycache__/line_numbers.cpython-312.pyc,,
+asttokens/__pycache__/mark_tokens.cpython-312.pyc,,
+asttokens/__pycache__/util.cpython-312.pyc,,
+asttokens/__pycache__/version.cpython-312.pyc,,
+asttokens/astroid_compat.py,sha256=ilaVBRWcHpQ3ZLBSBs9usUwnLW3Orfn6sM89cMN8zNI,586
+asttokens/asttokens.py,sha256=CQZ0ppXgTzHGbK4dqI4toSLywHIiqNK8jIVqbQClzYI,17760
+asttokens/line_numbers.py,sha256=ODbdlHI4Iht4UnSfsxmOHCIVw4c2XX7j-MdaCa6F8bo,2834
+asttokens/mark_tokens.py,sha256=YKE88IHnYyQiNvlFlxqU-BDhRRWkYYjMEsjxKlF1cqw,21012
+asttokens/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+asttokens/util.py,sha256=zkszPUVGR0-UxZJI-I4lTrA7yH2IUOz8IBmwGas-pbs,17286
+asttokens/version.py,sha256=EPmgXOdWKks5S__ZMH7Nu6xpAeVrZpfxaFy4pykuyeI,22

venv/Lib/site-packages/asttokens-3.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

venv/Lib/site-packages/asttokens-3.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+asttokens

venv/Lib/site-packages/asttokens/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2016 Grist Labs, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This module enhances the Python AST tree with token and source code information, sufficent to
+detect the source text of each AST node. This is helpful for tools that make source code
+transformations.
+"""
+
+from .line_numbers import LineNumbers
+from .asttokens import ASTText, ASTTokens, supports_tokenless
+
+__all__ = ['ASTText', 'ASTTokens', 'LineNumbers', 'supports_tokenless']

venv/Lib/site-packages/asttokens/astroid_compat.py

@@ -0,0 +1,18 @@
+try:
+  from astroid import nodes as astroid_node_classes
+
+  # astroid_node_classes should be whichever module has the NodeNG class
+  from astroid.nodes import NodeNG
+  from astroid.nodes import BaseContainer
+except Exception:
+  try:
+    from astroid import node_classes as astroid_node_classes
+    from astroid.node_classes import NodeNG
+    from astroid.node_classes import _BaseContainer as BaseContainer
+  except Exception:  # pragma: no cover
+    astroid_node_classes = None
+    NodeNG = None
+    BaseContainer = None
+
+
+__all__ = ["astroid_node_classes", "NodeNG", "BaseContainer"]

venv/Lib/site-packages/asttokens/asttokens.py

@@ -0,0 +1,450 @@
+# Copyright 2016 Grist Labs, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import abc
+import ast
+import bisect
+import sys
+import token
+from ast import Module
+from typing import Iterable, Iterator, List, Optional, Tuple, Any, cast, TYPE_CHECKING
+
+from .line_numbers import LineNumbers
+from .util import (
+  Token, match_token, is_non_coding_token, patched_generate_tokens, last_stmt,
+  annotate_fstring_nodes, generate_tokens, is_module, is_stmt
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+  from .util import AstNode, TokenInfo
+
+
+class ASTTextBase(metaclass=abc.ABCMeta):
+  def __init__(self, source_text: str, filename: str) -> None:
+    self._filename = filename
+
+    # Decode source after parsing to let Python 2 handle coding declarations.
+    # (If the encoding was not utf-8 compatible, then even if it parses correctly,
+    # we'll fail with a unicode error here.)
+    source_text = str(source_text)
+
+    self._text = source_text
+    self._line_numbers = LineNumbers(source_text)
+
+  @abc.abstractmethod
+  def get_text_positions(self, node, padded):
+    # type: (AstNode, bool) -> Tuple[Tuple[int, int], Tuple[int, int]]
+    """
+    Returns two ``(lineno, col_offset)`` tuples for the start and end of the given node.
+    If the positions can't be determined, or the nodes don't correspond to any particular text,
+    returns ``(1, 0)`` for both.
+
+    ``padded`` corresponds to the ``padded`` argument to ``ast.get_source_segment()``.
+    This means that if ``padded`` is True, the start position will be adjusted to include
+    leading whitespace if ``node`` is a multiline statement.
+    """
+    raise NotImplementedError  # pragma: no cover
+
+  def get_text_range(self, node, padded=True):
+    # type: (AstNode, bool) -> Tuple[int, int]
+    """
+    Returns the (startpos, endpos) positions in source text corresponding to the given node.
+    Returns (0, 0) for nodes (like `Load`) that don't correspond to any particular text.
+
+    See ``get_text_positions()`` for details on the ``padded`` argument.
+    """
+    start, end = self.get_text_positions(node, padded)
+    return (
+      self._line_numbers.line_to_offset(*start),
+      self._line_numbers.line_to_offset(*end),
+    )
+
+  def get_text(self, node, padded=True):
+    # type: (AstNode, bool) -> str
+    """
+    Returns the text corresponding to the given node.
+    Returns '' for nodes (like `Load`) that don't correspond to any particular text.
+
+    See ``get_text_positions()`` for details on the ``padded`` argument.
+    """
+    start, end = self.get_text_range(node, padded)
+    return self._text[start: end]
+
+
+class ASTTokens(ASTTextBase):
+  """
+  ASTTokens maintains the text of Python code in several forms: as a string, as line numbers, and
+  as tokens, and is used to mark and access token and position information.
+
+  ``source_text`` must be a unicode or UTF8-encoded string. If you pass in UTF8 bytes, remember
+  that all offsets you'll get are to the unicode text, which is available as the ``.text``
+  property.
+
+  If ``parse`` is set, the ``source_text`` will be parsed with ``ast.parse()``, and the resulting
+  tree marked with token info and made available as the ``.tree`` property.
+
+  If ``tree`` is given, it will be marked and made available as the ``.tree`` property. In
+  addition to the trees produced by the ``ast`` module, ASTTokens will also mark trees produced
+  using ``astroid`` library <https://www.astroid.org>.
+
+  If only ``source_text`` is given, you may use ``.mark_tokens(tree)`` to mark the nodes of an AST
+  tree created separately.
+  """
+
+  def __init__(self, source_text, parse=False, tree=None, filename='<unknown>', tokens=None):
+    # type: (Any, bool, Optional[Module], str, Iterable[TokenInfo]) -> None
+    super(ASTTokens, self).__init__(source_text, filename)
+
+    self._tree = ast.parse(source_text, filename) if parse else tree
+
+    # Tokenize the code.
+    if tokens is None:
+      tokens = generate_tokens(self._text)
+    self._tokens = list(self._translate_tokens(tokens))
+
+    # Extract the start positions of all tokens, so that we can quickly map positions to tokens.
+    self._token_offsets = [tok.startpos for tok in self._tokens]
+
+    if self._tree:
+      self.mark_tokens(self._tree)
+
+  def mark_tokens(self, root_node):
+    # type: (Module) -> None
+    """
+    Given the root of the AST or Astroid tree produced from source_text, visits all nodes marking
+    them with token and position information by adding ``.first_token`` and
+    ``.last_token`` attributes. This is done automatically in the constructor when ``parse`` or
+    ``tree`` arguments are set, but may be used manually with a separate AST or Astroid tree.
+    """
+    # The hard work of this class is done by MarkTokens
+    from .mark_tokens import MarkTokens  # to avoid import loops
+    MarkTokens(self).visit_tree(root_node)
+
+  def _translate_tokens(self, original_tokens):
+    # type: (Iterable[TokenInfo]) -> Iterator[Token]
+    """
+    Translates the given standard library tokens into our own representation.
+    """
+    for index, tok in enumerate(patched_generate_tokens(original_tokens)):
+      tok_type, tok_str, start, end, line = tok
+      yield Token(tok_type, tok_str, start, end, line, index,
+                  self._line_numbers.line_to_offset(start[0], start[1]),
+                  self._line_numbers.line_to_offset(end[0], end[1]))
+
+  @property
+  def text(self):
+    # type: () -> str
+    """The source code passed into the constructor."""
+    return self._text
+
+  @property
+  def tokens(self):
+    # type: () -> List[Token]
+    """The list of tokens corresponding to the source code from the constructor."""
+    return self._tokens
+
+  @property
+  def tree(self):
+    # type: () -> Optional[Module]
+    """The root of the AST tree passed into the constructor or parsed from the source code."""
+    return self._tree
+
+  @property
+  def filename(self):
+    # type: () -> str
+    """The filename that was parsed"""
+    return self._filename
+
+  def get_token_from_offset(self, offset):
+    # type: (int) -> Token
+    """
+    Returns the token containing the given character offset (0-based position in source text),
+    or the preceeding token if the position is between tokens.
+    """
+    return self._tokens[bisect.bisect(self._token_offsets, offset) - 1]
+
+  def get_token(self, lineno, col_offset):
+    # type: (int, int) -> Token
+    """
+    Returns the token containing the given (lineno, col_offset) position, or the preceeding token
+    if the position is between tokens.
+    """
+    # TODO: add test for multibyte unicode. We need to translate offsets from ast module (which
+    # are in utf8) to offsets into the unicode text. tokenize module seems to use unicode offsets
+    # but isn't explicit.
+    return self.get_token_from_offset(self._line_numbers.line_to_offset(lineno, col_offset))
+
+  def get_token_from_utf8(self, lineno, col_offset):
+    # type: (int, int) -> Token
+    """
+    Same as get_token(), but interprets col_offset as a UTF8 offset, which is what `ast` uses.
+    """
+    return self.get_token(lineno, self._line_numbers.from_utf8_col(lineno, col_offset))
+
+  def next_token(self, tok, include_extra=False):
+    # type: (Token, bool) -> Token
+    """
+    Returns the next token after the given one. If include_extra is True, includes non-coding
+    tokens from the tokenize module, such as NL and COMMENT.
+    """
+    i = tok.index + 1
+    if not include_extra:
+      while is_non_coding_token(self._tokens[i].type):
+        i += 1
+    return self._tokens[i]
+
+  def prev_token(self, tok, include_extra=False):
+    # type: (Token, bool) -> Token
+    """
+    Returns the previous token before the given one. If include_extra is True, includes non-coding
+    tokens from the tokenize module, such as NL and COMMENT.
+    """
+    i = tok.index - 1
+    if not include_extra:
+      while is_non_coding_token(self._tokens[i].type):
+        i -= 1
+    return self._tokens[i]
+
+  def find_token(self, start_token, tok_type, tok_str=None, reverse=False):
+    # type: (Token, int, Optional[str], bool) -> Token
+    """
+    Looks for the first token, starting at start_token, that matches tok_type and, if given, the
+    token string. Searches backwards if reverse is True. Returns ENDMARKER token if not found (you
+    can check it with `token.ISEOF(t.type)`).
+    """
+    t = start_token
+    advance = self.prev_token if reverse else self.next_token
+    while not match_token(t, tok_type, tok_str) and not token.ISEOF(t.type):
+      t = advance(t, include_extra=True)
+    return t
+
+  def token_range(self,
+                  first_token,  # type: Token
+                  last_token,  # type: Token
+                  include_extra=False,  # type: bool
+                  ):
+    # type: (...) -> Iterator[Token]
+    """
+    Yields all tokens in order from first_token through and including last_token. If
+    include_extra is True, includes non-coding tokens such as tokenize.NL and .COMMENT.
+    """
+    for i in range(first_token.index, last_token.index + 1):
+      if include_extra or not is_non_coding_token(self._tokens[i].type):
+        yield self._tokens[i]
+
+  def get_tokens(self, node, include_extra=False):
+    # type: (AstNode, bool) -> Iterator[Token]
+    """
+    Yields all tokens making up the given node. If include_extra is True, includes non-coding
+    tokens such as tokenize.NL and .COMMENT.
+    """
+    return self.token_range(node.first_token, node.last_token, include_extra=include_extra)
+
+  def get_text_positions(self, node, padded):
+    # type: (AstNode, bool) -> Tuple[Tuple[int, int], Tuple[int, int]]
+    """
+    Returns two ``(lineno, col_offset)`` tuples for the start and end of the given node.
+    If the positions can't be determined, or the nodes don't correspond to any particular text,
+    returns ``(1, 0)`` for both.
+
+    ``padded`` corresponds to the ``padded`` argument to ``ast.get_source_segment()``.
+    This means that if ``padded`` is True, the start position will be adjusted to include
+    leading whitespace if ``node`` is a multiline statement.
+    """
+    if not hasattr(node, 'first_token'):
+      return (1, 0), (1, 0)
+
+    start = node.first_token.start
+    end = node.last_token.end
+    if padded and any(match_token(t, token.NEWLINE) for t in self.get_tokens(node)):
+      # Set col_offset to 0 to include leading indentation for multiline statements.
+      start = (start[0], 0)
+
+    return start, end
+
+
+class ASTText(ASTTextBase):
+  """
+  Supports the same ``get_text*`` methods as ``ASTTokens``,
+  but uses the AST to determine the text positions instead of tokens.
+  This is faster than ``ASTTokens`` as it requires less setup work.
+
+  It also (sometimes) supports nodes inside f-strings, which ``ASTTokens`` doesn't.
+
+  Some node types and/or Python versions are not supported.
+  In these cases the ``get_text*`` methods will fall back to using ``ASTTokens``
+  which incurs the usual setup cost the first time.
+  If you want to avoid this, check ``supports_tokenless(node)`` before calling ``get_text*`` methods.
+  """
+  def __init__(self, source_text, tree=None, filename='<unknown>'):
+    # type: (Any, Optional[Module], str) -> None
+    super(ASTText, self).__init__(source_text, filename)
+
+    self._tree = tree
+    if self._tree is not None:
+      annotate_fstring_nodes(self._tree)
+
+    self._asttokens = None  # type: Optional[ASTTokens]
+
+  @property
+  def tree(self):
+    # type: () -> Module
+    if self._tree is None:
+      self._tree = ast.parse(self._text, self._filename)
+      annotate_fstring_nodes(self._tree)
+    return self._tree
+
+  @property
+  def asttokens(self):
+    # type: () -> ASTTokens
+    if self._asttokens is None:
+      self._asttokens = ASTTokens(
+          self._text,
+          tree=self.tree,
+          filename=self._filename,
+      )
+    return self._asttokens
+
+  def _get_text_positions_tokenless(self, node, padded):
+    # type: (AstNode, bool) -> Tuple[Tuple[int, int], Tuple[int, int]]
+    """
+    Version of ``get_text_positions()`` that doesn't use tokens.
+    """
+    if is_module(node):
+      # Modules don't have position info, so just return the range of the whole text.
+      # The token-using method does something different, but its behavior seems weird and inconsistent.
+      # For example, in a file with only comments, it only returns the first line.
+      # It's hard to imagine a case when this matters.
+      return (1, 0), self._line_numbers.offset_to_line(len(self._text))
+
+    if getattr(node, 'lineno', None) is None:
+      return (1, 0), (1, 0)
+
+    assert node  # tell mypy that node is not None, which we allowed up to here for compatibility
+
+    decorators = getattr(node, 'decorator_list', [])
+    if not decorators:
+      # Astroid uses node.decorators.nodes instead of node.decorator_list.
+      decorators_node = getattr(node, 'decorators', None)
+      decorators = getattr(decorators_node, 'nodes', [])
+    if decorators:
+      # Function/Class definition nodes are marked by AST as starting at def/class,
+      # not the first decorator. This doesn't match the token-using behavior,
+      # or inspect.getsource(), and just seems weird.
+      start_node = decorators[0]
+    else:
+      start_node = node
+
+    start_lineno = start_node.lineno
+    end_node = last_stmt(node)
+
+    # Include leading indentation for multiline statements.
+    # This doesn't mean simple statements that happen to be on multiple lines,
+    # but compound statements where inner indentation matters.
+    # So we don't just compare node.lineno and node.end_lineno,
+    # we check for a contained statement starting on a different line.
+    if padded and (
+        start_lineno != end_node.lineno
+        or (
+            # Astroid docstrings aren't treated as separate statements.
+            # So to handle function/class definitions with a docstring but no other body,
+            # we just check that the node is a statement with a docstring
+            # and spanning multiple lines in the simple, literal sense.
+            start_lineno != node.end_lineno
+            and getattr(node, "doc_node", None)
+            and is_stmt(node)
+        )
+    ):
+      start_col_offset = 0
+    else:
+      start_col_offset = self._line_numbers.from_utf8_col(start_lineno, start_node.col_offset)
+
+    start = (start_lineno, start_col_offset)
+
+    # To match the token-using behaviour, we exclude trailing semicolons and comments.
+    # This means that for blocks containing multiple statements, we have to use the last one
+    # instead of the actual node for end_lineno and end_col_offset.
+    end_lineno = cast(int, end_node.end_lineno)
+    end_col_offset = cast(int, end_node.end_col_offset)
+    end_col_offset = self._line_numbers.from_utf8_col(end_lineno, end_col_offset)
+    end = (end_lineno, end_col_offset)
+
+    return start, end
+
+  def get_text_positions(self, node, padded):
+    # type: (AstNode, bool) -> Tuple[Tuple[int, int], Tuple[int, int]]
+    """
+    Returns two ``(lineno, col_offset)`` tuples for the start and end of the given node.
+    If the positions can't be determined, or the nodes don't correspond to any particular text,
+    returns ``(1, 0)`` for both.
+
+    ``padded`` corresponds to the ``padded`` argument to ``ast.get_source_segment()``.
+    This means that if ``padded`` is True, the start position will be adjusted to include
+    leading whitespace if ``node`` is a multiline statement.
+    """
+    if getattr(node, "_broken_positions", None):
+      # This node was marked in util.annotate_fstring_nodes as having untrustworthy lineno/col_offset.
+      return (1, 0), (1, 0)
+
+    if supports_tokenless(node):
+      return self._get_text_positions_tokenless(node, padded)
+
+    return self.asttokens.get_text_positions(node, padded)
+
+
+# Node types that _get_text_positions_tokenless doesn't support.
+# These initial values are missing lineno.
+_unsupported_tokenless_types = ("arguments", "Arguments", "withitem")  # type: Tuple[str, ...]
+if sys.version_info[:2] == (3, 8):
+  # _get_text_positions_tokenless works incorrectly for these types due to bugs in Python 3.8.
+  _unsupported_tokenless_types += ("arg", "Starred")
+  # no lineno in 3.8
+  _unsupported_tokenless_types += ("Slice", "ExtSlice", "Index", "keyword")
+
+
+def supports_tokenless(node=None):
+  # type: (Any) -> bool
+  """
+  Returns True if the Python version and the node (if given) are supported by
+  the ``get_text*`` methods of ``ASTText`` without falling back to ``ASTTokens``.
+  See ``ASTText`` for why this matters.
+
+  The following cases are not supported:
+
+    - PyPy
+    - ``ast.arguments`` / ``astroid.Arguments``
+    - ``ast.withitem``
+    - ``astroid.Comprehension``
+    - ``astroid.AssignName`` inside ``astroid.Arguments`` or ``astroid.ExceptHandler``
+    - The following nodes in Python 3.8 only:
+      - ``ast.arg``
+      - ``ast.Starred``
+      - ``ast.Slice``
+      - ``ast.ExtSlice``
+      - ``ast.Index``
+      - ``ast.keyword``
+  """
+  return (
+      type(node).__name__ not in _unsupported_tokenless_types
+      and not (
+        # astroid nodes
+        not isinstance(node, ast.AST) and node is not None and (
+          (
+            type(node).__name__ == "AssignName"
+            and type(node.parent).__name__ in ("Arguments", "ExceptHandler")
+          )
+        )
+      )
+      and 'pypy' not in sys.version.lower()
+  )

venv/Lib/site-packages/asttokens/line_numbers.py

@@ -0,0 +1,76 @@
+# Copyright 2016 Grist Labs, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import bisect
+import re
+from typing import Dict, List, Tuple
+
+_line_start_re = re.compile(r'^', re.M)
+
+class LineNumbers:
+  """
+  Class to convert between character offsets in a text string, and pairs (line, column) of 1-based
+  line and 0-based column numbers, as used by tokens and AST nodes.
+
+  This class expects unicode for input and stores positions in unicode. But it supports
+  translating to and from utf8 offsets, which are used by ast parsing.
+  """
+  def __init__(self, text):
+    # type: (str) -> None
+    # A list of character offsets of each line's first character.
+    self._line_offsets = [m.start(0) for m in _line_start_re.finditer(text)]
+    self._text = text
+    self._text_len = len(text)
+    self._utf8_offset_cache = {} # type: Dict[int, List[int]] # maps line num to list of char offset for each byte in line
+
+  def from_utf8_col(self, line, utf8_column):
+    # type: (int, int) -> int
+    """
+    Given a 1-based line number and 0-based utf8 column, returns a 0-based unicode column.
+    """
+    offsets = self._utf8_offset_cache.get(line)
+    if offsets is None:
+      end_offset = self._line_offsets[line] if line < len(self._line_offsets) else self._text_len
+      line_text = self._text[self._line_offsets[line - 1] : end_offset]
+
+      offsets = [i for i,c in enumerate(line_text) for byte in c.encode('utf8')]
+      offsets.append(len(line_text))
+      self._utf8_offset_cache[line] = offsets
+
+    return offsets[max(0, min(len(offsets)-1, utf8_column))]
+
+  def line_to_offset(self, line, column):
+    # type: (int, int) -> int
+    """
+    Converts 1-based line number and 0-based column to 0-based character offset into text.
+    """
+    line -= 1
+    if line >= len(self._line_offsets):
+      return self._text_len
+    elif line < 0:
+      return 0
+    else:
+      return min(self._line_offsets[line] + max(0, column), self._text_len)
+
+  def offset_to_line(self, offset):
+    # type: (int) -> Tuple[int, int]
+    """
+    Converts 0-based character offset to pair (line, col) of 1-based line and 0-based column
+    numbers.
+    """
+    offset = max(0, min(self._text_len, offset))
+    line_index = bisect.bisect_right(self._line_offsets, offset) - 1
+    return (line_index + 1, offset - self._line_offsets[line_index])
+
+

venv/Lib/site-packages/asttokens/mark_tokens.py

@@ -0,0 +1,467 @@
+# Copyright 2016 Grist Labs, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import ast
+import numbers
+import sys
+import token
+from ast import Module
+from typing import Callable, List, Union, cast, Optional, Tuple, TYPE_CHECKING
+
+from . import util
+from .asttokens import ASTTokens
+from .astroid_compat import astroid_node_classes as nc, BaseContainer as AstroidBaseContainer
+
+if TYPE_CHECKING:
+  from .util import AstNode
+
+
+# Mapping of matching braces. To find a token here, look up token[:2].
+_matching_pairs_left = {
+  (token.OP, '('): (token.OP, ')'),
+  (token.OP, '['): (token.OP, ']'),
+  (token.OP, '{'): (token.OP, '}'),
+}
+
+_matching_pairs_right = {
+  (token.OP, ')'): (token.OP, '('),
+  (token.OP, ']'): (token.OP, '['),
+  (token.OP, '}'): (token.OP, '{'),
+}
+
+
+class MarkTokens:
+  """
+  Helper that visits all nodes in the AST tree and assigns .first_token and .last_token attributes
+  to each of them. This is the heart of the token-marking logic.
+  """
+  def __init__(self, code):
+    # type: (ASTTokens) -> None
+    self._code = code
+    self._methods = util.NodeMethods()
+    self._iter_children = None # type: Optional[Callable]
+
+  def visit_tree(self, node):
+    # type: (Module) -> None
+    self._iter_children = util.iter_children_func(node)
+    util.visit_tree(node, self._visit_before_children, self._visit_after_children)
+
+  def _visit_before_children(self, node, parent_token):
+    # type: (AstNode, Optional[util.Token]) -> Tuple[Optional[util.Token], Optional[util.Token]]
+    col = getattr(node, 'col_offset', None)
+    token = self._code.get_token_from_utf8(node.lineno, col) if col is not None else None
+
+    if not token and util.is_module(node):
+      # We'll assume that a Module node starts at the start of the source code.
+      token = self._code.get_token(1, 0)
+
+    # Use our own token, or our parent's if we don't have one, to pass to child calls as
+    # parent_token argument. The second value becomes the token argument of _visit_after_children.
+    return (token or parent_token, token)
+
+  def _visit_after_children(self, node, parent_token, token):
+    # type: (AstNode, Optional[util.Token], Optional[util.Token]) -> None
+    # This processes the node generically first, after all children have been processed.
+
+    # Get the first and last tokens that belong to children. Note how this doesn't assume that we
+    # iterate through children in order that corresponds to occurrence in source code. This
+    # assumption can fail (e.g. with return annotations).
+    first = token
+    last = None
+    for child in cast(Callable, self._iter_children)(node):
+      # astroid slices have especially wrong positions, we don't want them to corrupt their parents.
+      if util.is_empty_astroid_slice(child):
+        continue
+      if not first or child.first_token.index < first.index:
+        first = child.first_token
+      if not last or child.last_token.index > last.index:
+        last = child.last_token
+
+    # If we don't have a first token from _visit_before_children, and there were no children, then
+    # use the parent's token as the first token.
+    first = first or parent_token
+
+    # If no children, set last token to the first one.
+    last = last or first
+
+    # Statements continue to before NEWLINE. This helps cover a few different cases at once.
+    if util.is_stmt(node):
+      last = self._find_last_in_stmt(cast(util.Token, last))
+
+    # Capture any unmatched brackets.
+    first, last = self._expand_to_matching_pairs(cast(util.Token, first), cast(util.Token, last), node)
+
+    # Give a chance to node-specific methods to adjust.
+    nfirst, nlast = self._methods.get(self, node.__class__)(node, first, last)
+
+    if (nfirst, nlast) != (first, last):
+      # If anything changed, expand again to capture any unmatched brackets.
+      nfirst, nlast = self._expand_to_matching_pairs(nfirst, nlast, node)
+
+    node.first_token = nfirst
+    node.last_token = nlast
+
+  def _find_last_in_stmt(self, start_token):
+    # type: (util.Token) -> util.Token
+    t = start_token
+    while (not util.match_token(t, token.NEWLINE) and
+           not util.match_token(t, token.OP, ';') and
+           not token.ISEOF(t.type)):
+      t = self._code.next_token(t, include_extra=True)
+    return self._code.prev_token(t)
+
+  def _expand_to_matching_pairs(self, first_token, last_token, node):
+    # type: (util.Token, util.Token, AstNode) -> Tuple[util.Token, util.Token]
+    """
+    Scan tokens in [first_token, last_token] range that are between node's children, and for any
+    unmatched brackets, adjust first/last tokens to include the closing pair.
+    """
+    # We look for opening parens/braces among non-child tokens (i.e. tokens between our actual
+    # child nodes). If we find any closing ones, we match them to the opens.
+    to_match_right = [] # type: List[Tuple[int, str]]
+    to_match_left = []
+    for tok in self._code.token_range(first_token, last_token):
+      tok_info = tok[:2]
+      if to_match_right and tok_info == to_match_right[-1]:
+        to_match_right.pop()
+      elif tok_info in _matching_pairs_left:
+        to_match_right.append(_matching_pairs_left[tok_info])
+      elif tok_info in _matching_pairs_right:
+        to_match_left.append(_matching_pairs_right[tok_info])
+
+    # Once done, extend `last_token` to match any unclosed parens/braces.
+    for match in reversed(to_match_right):
+      last = self._code.next_token(last_token)
+      # Allow for trailing commas or colons (allowed in subscripts) before the closing delimiter
+      while any(util.match_token(last, token.OP, x) for x in (',', ':')):
+        last = self._code.next_token(last)
+      # Now check for the actual closing delimiter.
+      if util.match_token(last, *match):
+        last_token = last
+
+    # And extend `first_token` to match any unclosed opening parens/braces.
+    for match in to_match_left:
+      first = self._code.prev_token(first_token)
+      if util.match_token(first, *match):
+        first_token = first
+
+    return (first_token, last_token)
+
+  #----------------------------------------------------------------------
+  # Node visitors. Each takes a preliminary first and last tokens, and returns the adjusted pair
+  # that will actually be assigned.
+
+  def visit_default(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # pylint: disable=no-self-use
+    # By default, we don't need to adjust the token we computed earlier.
+    return (first_token, last_token)
+
+  def handle_comp(self, open_brace, node, first_token, last_token):
+    # type: (str, AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # For list/set/dict comprehensions, we only get the token of the first child, so adjust it to
+    # include the opening brace (the closing brace will be matched automatically).
+    before = self._code.prev_token(first_token)
+    util.expect_token(before, token.OP, open_brace)
+    return (before, last_token)
+
+  def visit_comprehension(self,
+                          node,  # type: AstNode
+                          first_token,  # type: util.Token
+                          last_token,  # type: util.Token
+                          ):
+    # type: (...) -> Tuple[util.Token, util.Token]
+    # The 'comprehension' node starts with 'for' but we only get first child; we search backwards
+    # to find the 'for' keyword.
+    first = self._code.find_token(first_token, token.NAME, 'for', reverse=True)
+    return (first, last_token)
+
+  def visit_if(self, node, first_token, last_token):
+    # type: (util.Token, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    while first_token.string not in ('if', 'elif'):
+      first_token = self._code.prev_token(first_token)
+    return first_token, last_token
+
+  def handle_attr(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # Attribute node has ".attr" (2 tokens) after the last child.
+    dot = self._code.find_token(last_token, token.OP, '.')
+    name = self._code.next_token(dot)
+    util.expect_token(name, token.NAME)
+    return (first_token, name)
+
+  visit_attribute = handle_attr
+  visit_assignattr = handle_attr
+  visit_delattr = handle_attr
+
+  def handle_def(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # With astroid, nodes that start with a doc-string can have an empty body, in which case we
+    # need to adjust the last token to include the doc string.
+    if not node.body and (getattr(node, 'doc_node', None) or getattr(node, 'doc', None)): # type: ignore[union-attr]
+      last_token = self._code.find_token(last_token, token.STRING)
+
+    # Include @ from decorator
+    if first_token.index > 0:
+      prev = self._code.prev_token(first_token)
+      if util.match_token(prev, token.OP, '@'):
+        first_token = prev
+    return (first_token, last_token)
+
+  visit_classdef = handle_def
+  visit_functiondef = handle_def
+
+  def handle_following_brackets(self, node, last_token, opening_bracket):
+    # type: (AstNode, util.Token, str) -> util.Token
+    # This is for calls and subscripts, which have a pair of brackets
+    # at the end which may contain no nodes, e.g. foo() or bar[:].
+    # We look for the opening bracket and then let the matching pair be found automatically
+    # Remember that last_token is at the end of all children,
+    # so we are not worried about encountering a bracket that belongs to a child.
+    first_child = next(cast(Callable, self._iter_children)(node))
+    call_start = self._code.find_token(first_child.last_token, token.OP, opening_bracket)
+    if call_start.index > last_token.index:
+      last_token = call_start
+    return last_token
+
+  def visit_call(self, node, first_token, last_token):
+    # type: (util.Token, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    last_token = self.handle_following_brackets(node, last_token, '(')
+
+    # Handling a python bug with decorators with empty parens, e.g.
+    # @deco()
+    # def ...
+    if util.match_token(first_token, token.OP, '@'):
+      first_token = self._code.next_token(first_token)
+    return (first_token, last_token)
+
+  def visit_matchclass(self, node, first_token, last_token):
+    # type: (util.Token, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    last_token = self.handle_following_brackets(node, last_token, '(')
+    return (first_token, last_token)
+
+  def visit_subscript(self,
+                      node,  # type: AstNode
+                      first_token,  # type: util.Token
+                      last_token,  # type: util.Token
+                      ):
+    # type: (...) -> Tuple[util.Token, util.Token]
+    last_token = self.handle_following_brackets(node, last_token, '[')
+    return (first_token, last_token)
+
+  def visit_slice(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # consume `:` tokens to the left and right. In Python 3.9, Slice nodes are
+    # given a col_offset, (and end_col_offset), so this will always start inside
+    # the slice, even if it is the empty slice. However, in 3.8 and below, this
+    # will only expand to the full slice if the slice contains a node with a
+    # col_offset. So x[:] will only get the correct tokens in 3.9, but x[1:] and
+    # x[:1] will even on earlier versions of Python.
+    while True:
+      prev = self._code.prev_token(first_token)
+      if prev.string != ':':
+        break
+      first_token = prev
+    while True:
+      next_ = self._code.next_token(last_token)
+      if next_.string != ':':
+        break
+      last_token = next_
+    return (first_token, last_token)
+
+  def handle_bare_tuple(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # A bare tuple doesn't include parens; if there is a trailing comma, make it part of the tuple.
+    maybe_comma = self._code.next_token(last_token)
+    if util.match_token(maybe_comma, token.OP, ','):
+      last_token = maybe_comma
+    return (first_token, last_token)
+
+  # In Python3.8 parsed tuples include parentheses when present.
+  def handle_tuple_nonempty(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    assert isinstance(node, ast.Tuple) or isinstance(node, AstroidBaseContainer)
+    # It's a bare tuple if the first token belongs to the first child. The first child may
+    # include extraneous parentheses (which don't create new nodes), so account for those too.
+    child = node.elts[0]
+    if TYPE_CHECKING:
+      child = cast(AstNode, child)
+    child_first, child_last = self._gobble_parens(child.first_token, child.last_token, True)
+    if first_token == child_first:
+      return self.handle_bare_tuple(node, first_token, last_token)
+    return (first_token, last_token)
+
+  def visit_tuple(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    assert isinstance(node, ast.Tuple) or isinstance(node, AstroidBaseContainer)
+    if not node.elts:
+      # An empty tuple is just "()", and we need no further info.
+      return (first_token, last_token)
+    return self.handle_tuple_nonempty(node, first_token, last_token)
+
+  def _gobble_parens(self, first_token, last_token, include_all=False):
+    # type: (util.Token, util.Token, bool) -> Tuple[util.Token, util.Token]
+    # Expands a range of tokens to include one or all pairs of surrounding parentheses, and
+    # returns (first, last) tokens that include these parens.
+    while first_token.index > 0:
+      prev = self._code.prev_token(first_token)
+      next = self._code.next_token(last_token)
+      if util.match_token(prev, token.OP, '(') and util.match_token(next, token.OP, ')'):
+        first_token, last_token = prev, next
+        if include_all:
+          continue
+      break
+    return (first_token, last_token)
+
+  def visit_str(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    return self.handle_str(first_token, last_token)
+
+  def visit_joinedstr(self,
+                      node,  # type: AstNode
+                      first_token,  # type: util.Token
+                      last_token,  # type: util.Token
+                      ):
+    # type: (...) -> Tuple[util.Token, util.Token]
+    if sys.version_info < (3, 12):
+      # Older versions don't tokenize the contents of f-strings
+      return self.handle_str(first_token, last_token)
+
+    last = first_token
+    while True:
+      if util.match_token(last, getattr(token, "FSTRING_START")):
+        # Python 3.12+ has tokens for the start (e.g. `f"`) and end (`"`)
+        # of the f-string. We can't just look for the next FSTRING_END
+        # because f-strings can be nested, e.g. f"{f'{x}'}", so we need
+        # to treat this like matching balanced parentheses.
+        count = 1
+        while count > 0:
+          last = self._code.next_token(last)
+          # mypy complains about token.FSTRING_START and token.FSTRING_END.
+          if util.match_token(last, getattr(token, "FSTRING_START")):
+            count += 1
+          elif util.match_token(last, getattr(token, "FSTRING_END")):
+            count -= 1
+        last_token = last
+        last = self._code.next_token(last_token)
+      elif util.match_token(last, token.STRING):
+        # Similar to handle_str, we also need to handle adjacent strings.
+        last_token = last
+        last = self._code.next_token(last_token)
+      else:
+        break
+    return (first_token, last_token)
+
+  def visit_bytes(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    return self.handle_str(first_token, last_token)
+
+  def handle_str(self, first_token, last_token):
+    # type: (util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # Multiple adjacent STRING tokens form a single string.
+    last = self._code.next_token(last_token)
+    while util.match_token(last, token.STRING):
+      last_token = last
+      last = self._code.next_token(last_token)
+    return (first_token, last_token)
+
+  def handle_num(self,
+                 node,  # type: AstNode
+                 value,  # type: Union[complex, int, numbers.Number]
+                 first_token,  # type: util.Token
+                 last_token,  # type: util.Token
+                 ):
+    # type: (...) -> Tuple[util.Token, util.Token]
+    # A constant like '-1' gets turned into two tokens; this will skip the '-'.
+    while util.match_token(last_token, token.OP):
+      last_token = self._code.next_token(last_token)
+
+    if isinstance(value, complex):
+      # A complex number like -2j cannot be compared directly to 0
+      # A complex number like 1-2j is expressed as a binary operation
+      # so we don't need to worry about it
+      value = value.imag
+
+    # This makes sure that the - is included
+    if value < 0 and first_token.type == token.NUMBER: # type: ignore[operator]
+        first_token = self._code.prev_token(first_token)
+    return (first_token, last_token)
+
+  def visit_num(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    return self.handle_num(node, cast(ast.Num, node).n, first_token, last_token)
+
+  def visit_const(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    assert isinstance(node, ast.Constant) or isinstance(node, nc.Const)
+    if isinstance(node.value, numbers.Number):
+      return self.handle_num(node, node.value, first_token, last_token)
+    elif isinstance(node.value, (str, bytes)):
+      return self.visit_str(node, first_token, last_token)
+    return (first_token, last_token)
+
+  visit_constant = visit_const
+
+  def visit_keyword(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # Until python 3.9 (https://bugs.python.org/issue40141),
+    # ast.keyword nodes didn't have line info. Astroid has lineno None.
+    assert isinstance(node, ast.keyword) or isinstance(node, nc.Keyword)
+    if node.arg is not None and getattr(node, 'lineno', None) is None:
+      equals = self._code.find_token(first_token, token.OP, '=', reverse=True)
+      name = self._code.prev_token(equals)
+      util.expect_token(name, token.NAME, node.arg)
+      first_token = name
+    return (first_token, last_token)
+
+  def visit_starred(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # Astroid has 'Starred' nodes (for "foo(*bar)" type args), but they need to be adjusted.
+    if not util.match_token(first_token, token.OP, '*'):
+      star = self._code.prev_token(first_token)
+      if util.match_token(star, token.OP, '*'):
+        first_token = star
+    return (first_token, last_token)
+
+  def visit_assignname(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    # Astroid may turn 'except' clause into AssignName, but we need to adjust it.
+    if util.match_token(first_token, token.NAME, 'except'):
+      colon = self._code.find_token(last_token, token.OP, ':')
+      first_token = last_token = self._code.prev_token(colon)
+    return (first_token, last_token)
+
+  # Async nodes should typically start with the word 'async'
+  # but Python < 3.7 doesn't put the col_offset there
+  # AsyncFunctionDef is slightly different because it might have
+  # decorators before that, which visit_functiondef handles
+  def handle_async(self, node, first_token, last_token):
+    # type: (AstNode, util.Token, util.Token) -> Tuple[util.Token, util.Token]
+    if not first_token.string == 'async':
+      first_token = self._code.prev_token(first_token)
+    return (first_token, last_token)
+
+  visit_asyncfor = handle_async
+  visit_asyncwith = handle_async
+
+  def visit_asyncfunctiondef(self,
+                             node,  # type: AstNode
+                             first_token,  # type: util.Token
+                             last_token,  # type: util.Token
+                             ):
+    # type: (...) -> Tuple[util.Token, util.Token]
+    if util.match_token(first_token, token.NAME, 'def'):
+      # Include the 'async' token
+      first_token = self._code.prev_token(first_token)
+    return self.visit_functiondef(node, first_token, last_token)

venv/Lib/site-packages/asttokens/util.py

@@ -0,0 +1,485 @@
+# Copyright 2016 Grist Labs, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import ast
+import collections
+import io
+import sys
+import token
+import tokenize
+from abc import ABCMeta
+from ast import Module, expr, AST
+from functools import lru_cache
+from typing import (
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Optional,
+    Tuple,
+    Union,
+    cast,
+    Any,
+    TYPE_CHECKING,
+    Type,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+  from .astroid_compat import NodeNG
+
+  # Type class used to expand out the definition of AST to include fields added by this library
+  # It's not actually used for anything other than type checking though!
+  class EnhancedAST(AST):
+    # Additional attributes set by mark_tokens
+    first_token = None  # type: Token
+    last_token = None  # type: Token
+    lineno = 0  # type: int
+
+  AstNode = Union[EnhancedAST, NodeNG]
+
+  TokenInfo = tokenize.TokenInfo
+
+
+def token_repr(tok_type, string):
+  # type: (int, Optional[str]) -> str
+  """Returns a human-friendly representation of a token with the given type and string."""
+  # repr() prefixes unicode with 'u' on Python2 but not Python3; strip it out for consistency.
+  return '%s:%s' % (token.tok_name[tok_type], repr(string).lstrip('u'))
+
+
+class Token(collections.namedtuple('Token', 'type string start end line index startpos endpos')):
+  """
+  TokenInfo is an 8-tuple containing the same 5 fields as the tokens produced by the tokenize
+  module, and 3 additional ones useful for this module:
+
+  - [0] .type     Token type (see token.py)
+  - [1] .string   Token (a string)
+  - [2] .start    Starting (row, column) indices of the token (a 2-tuple of ints)
+  - [3] .end      Ending (row, column) indices of the token (a 2-tuple of ints)
+  - [4] .line     Original line (string)
+  - [5] .index    Index of the token in the list of tokens that it belongs to.
+  - [6] .startpos Starting character offset into the input text.
+  - [7] .endpos   Ending character offset into the input text.
+  """
+  def __str__(self):
+    # type: () -> str
+    return token_repr(self.type, self.string)
+
+
+def match_token(token, tok_type, tok_str=None):
+  # type: (Token, int, Optional[str]) -> bool
+  """Returns true if token is of the given type and, if a string is given, has that string."""
+  return token.type == tok_type and (tok_str is None or token.string == tok_str)
+
+
+def expect_token(token, tok_type, tok_str=None):
+  # type: (Token, int, Optional[str]) -> None
+  """
+  Verifies that the given token is of the expected type. If tok_str is given, the token string
+  is verified too. If the token doesn't match, raises an informative ValueError.
+  """
+  if not match_token(token, tok_type, tok_str):
+    raise ValueError("Expected token %s, got %s on line %s col %s" % (
+      token_repr(tok_type, tok_str), str(token),
+      token.start[0], token.start[1] + 1))
+
+
+def is_non_coding_token(token_type):
+  # type: (int) -> bool
+  """
+  These are considered non-coding tokens, as they don't affect the syntax tree.
+  """
+  return token_type in (token.NL, token.COMMENT, token.ENCODING)
+
+
+def generate_tokens(text):
+  # type: (str) -> Iterator[TokenInfo]
+  """
+  Generates standard library tokens for the given code.
+  """
+  # tokenize.generate_tokens is technically an undocumented API for Python3, but allows us to use the same API as for
+  # Python2. See http://stackoverflow.com/a/4952291/328565.
+  # FIXME: Remove cast once https://github.com/python/typeshed/issues/7003 gets fixed
+  return tokenize.generate_tokens(cast(Callable[[], str], io.StringIO(text).readline))
+
+
+def iter_children_func(node):
+  # type: (AST) -> Callable
+  """
+  Returns a function which yields all direct children of a AST node,
+  skipping children that are singleton nodes.
+  The function depends on whether ``node`` is from ``ast`` or from the ``astroid`` module.
+  """
+  return iter_children_astroid if hasattr(node, 'get_children') else iter_children_ast
+
+
+def iter_children_astroid(node, include_joined_str=False):
+  # type: (NodeNG, bool) -> Union[Iterator, List]
+  if not include_joined_str and is_joined_str(node):
+    return []
+
+  return node.get_children()
+
+
+SINGLETONS = {c for n, c in ast.__dict__.items() if isinstance(c, type) and
+              issubclass(c, (ast.expr_context, ast.boolop, ast.operator, ast.unaryop, ast.cmpop))}
+
+
+def iter_children_ast(node, include_joined_str=False):
+  # type: (AST, bool) -> Iterator[Union[AST, expr]]
+  if not include_joined_str and is_joined_str(node):
+    return
+
+  if isinstance(node, ast.Dict):
+    # override the iteration order: instead of <all keys>, <all values>,
+    # yield keys and values in source order (key1, value1, key2, value2, ...)
+    for (key, value) in zip(node.keys, node.values):
+      if key is not None:
+        yield key
+      yield value
+    return
+
+  for child in ast.iter_child_nodes(node):
+    # Skip singleton children; they don't reflect particular positions in the code and break the
+    # assumptions about the tree consisting of distinct nodes. Note that collecting classes
+    # beforehand and checking them in a set is faster than using isinstance each time.
+    if child.__class__ not in SINGLETONS:
+      yield child
+
+
+stmt_class_names = {n for n, c in ast.__dict__.items()
+                    if isinstance(c, type) and issubclass(c, ast.stmt)}
+expr_class_names = ({n for n, c in ast.__dict__.items()
+                    if isinstance(c, type) and issubclass(c, ast.expr)} |
+                    {'AssignName', 'DelName', 'Const', 'AssignAttr', 'DelAttr'})
+
+# These feel hacky compared to isinstance() but allow us to work with both ast and astroid nodes
+# in the same way, and without even importing astroid.
+def is_expr(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is an expression node."""
+  return node.__class__.__name__ in expr_class_names
+
+def is_stmt(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is a statement node."""
+  return node.__class__.__name__ in stmt_class_names
+
+def is_module(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is a module node."""
+  return node.__class__.__name__ == 'Module'
+
+def is_joined_str(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is a JoinedStr node, used to represent f-strings."""
+  # At the moment, nodes below JoinedStr have wrong line/col info, and trying to process them only
+  # leads to errors.
+  return node.__class__.__name__ == 'JoinedStr'
+
+
+def is_expr_stmt(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is an `Expr` node, which is a statement that is an expression."""
+  return node.__class__.__name__ == 'Expr'
+
+
+
+CONSTANT_CLASSES: Tuple[Type, ...] = (ast.Constant,)
+try:
+  from astroid import Const
+  CONSTANT_CLASSES += (Const,)
+except ImportError:  # pragma: no cover
+  # astroid is not available
+  pass
+
+def is_constant(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is a Constant node."""
+  return isinstance(node, CONSTANT_CLASSES)
+
+
+def is_ellipsis(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is an Ellipsis node."""
+  return is_constant(node) and node.value is Ellipsis  # type: ignore
+
+
+def is_starred(node):
+  # type: (AstNode) -> bool
+  """Returns whether node is a starred expression node."""
+  return node.__class__.__name__ == 'Starred'
+
+
+def is_slice(node):
+  # type: (AstNode) -> bool
+  """Returns whether node represents a slice, e.g. `1:2` in `x[1:2]`"""
+  # Before 3.9, a tuple containing a slice is an ExtSlice,
+  # but this was removed in https://bugs.python.org/issue34822
+  return (
+      node.__class__.__name__ in ('Slice', 'ExtSlice')
+      or (
+          node.__class__.__name__ == 'Tuple'
+          and any(map(is_slice, cast(ast.Tuple, node).elts))
+      )
+  )
+
+
+def is_empty_astroid_slice(node):
+  # type: (AstNode) -> bool
+  return (
+      node.__class__.__name__ == "Slice"
+      and not isinstance(node, ast.AST)
+      and node.lower is node.upper is node.step is None
+  )
+
+
+# Sentinel value used by visit_tree().
+_PREVISIT = object()
+
+def visit_tree(node, previsit, postvisit):
+  # type: (Module, Callable[[AstNode, Optional[Token]], Tuple[Optional[Token], Optional[Token]]], Optional[Callable[[AstNode, Optional[Token], Optional[Token]], None]])   -> None
+  """
+  Scans the tree under the node depth-first using an explicit stack. It avoids implicit recursion
+  via the function call stack to avoid hitting 'maximum recursion depth exceeded' error.
+
+  It calls ``previsit()`` and ``postvisit()`` as follows:
+
+  * ``previsit(node, par_value)`` - should return ``(par_value, value)``
+        ``par_value`` is as returned from ``previsit()`` of the parent.
+
+  * ``postvisit(node, par_value, value)`` - should return ``value``
+        ``par_value`` is as returned from ``previsit()`` of the parent, and ``value`` is as
+        returned from ``previsit()`` of this node itself. The return ``value`` is ignored except
+        the one for the root node, which is returned from the overall ``visit_tree()`` call.
+
+  For the initial node, ``par_value`` is None. ``postvisit`` may be None.
+  """
+  if not postvisit:
+    postvisit = lambda node, pvalue, value: None
+
+  iter_children = iter_children_func(node)
+  done = set()
+  ret = None
+  stack = [(node, None, _PREVISIT)] # type: List[Tuple[AstNode, Optional[Token], Union[Optional[Token], object]]]
+  while stack:
+    current, par_value, value = stack.pop()
+    if value is _PREVISIT:
+      assert current not in done    # protect againt infinite loop in case of a bad tree.
+      done.add(current)
+
+      pvalue, post_value = previsit(current, par_value)
+      stack.append((current, par_value, post_value))
+
+      # Insert all children in reverse order (so that first child ends up on top of the stack).
+      ins = len(stack)
+      for n in iter_children(current):
+        stack.insert(ins, (n, pvalue, _PREVISIT))
+    else:
+      ret = postvisit(current, par_value, cast(Optional[Token], value))
+  return ret
+
+
+def walk(node, include_joined_str=False):
+  # type: (AST, bool) -> Iterator[Union[Module, AstNode]]
+  """
+  Recursively yield all descendant nodes in the tree starting at ``node`` (including ``node``
+  itself), using depth-first pre-order traversal (yieling parents before their children).
+
+  This is similar to ``ast.walk()``, but with a different order, and it works for both ``ast`` and
+  ``astroid`` trees. Also, as ``iter_children()``, it skips singleton nodes generated by ``ast``.
+
+  By default, ``JoinedStr`` (f-string) nodes and their contents are skipped
+  because they previously couldn't be handled. Set ``include_joined_str`` to True to include them.
+  """
+  iter_children = iter_children_func(node)
+  done = set()
+  stack = [node]
+  while stack:
+    current = stack.pop()
+    assert current not in done    # protect againt infinite loop in case of a bad tree.
+    done.add(current)
+
+    yield current
+
+    # Insert all children in reverse order (so that first child ends up on top of the stack).
+    # This is faster than building a list and reversing it.
+    ins = len(stack)
+    for c in iter_children(current, include_joined_str):
+      stack.insert(ins, c)
+
+
+def replace(text, replacements):
+  # type: (str, List[Tuple[int, int, str]]) -> str
+  """
+  Replaces multiple slices of text with new values. This is a convenience method for making code
+  modifications of ranges e.g. as identified by ``ASTTokens.get_text_range(node)``. Replacements is
+  an iterable of ``(start, end, new_text)`` tuples.
+
+  For example, ``replace("this is a test", [(0, 4, "X"), (8, 9, "THE")])`` produces
+  ``"X is THE test"``.
+  """
+  p = 0
+  parts = []
+  for (start, end, new_text) in sorted(replacements):
+    parts.append(text[p:start])
+    parts.append(new_text)
+    p = end
+  parts.append(text[p:])
+  return ''.join(parts)
+
+
+class NodeMethods:
+  """
+  Helper to get `visit_{node_type}` methods given a node's class and cache the results.
+  """
+  def __init__(self):
+    # type: () -> None
+    self._cache = {} # type: Dict[Union[ABCMeta, type], Callable[[AstNode, Token, Token], Tuple[Token, Token]]]
+
+  def get(self, obj, cls):
+    # type: (Any, Union[ABCMeta, type]) -> Callable
+    """
+    Using the lowercase name of the class as node_type, returns `obj.visit_{node_type}`,
+    or `obj.visit_default` if the type-specific method is not found.
+    """
+    method = self._cache.get(cls)
+    if not method:
+      name = "visit_" + cls.__name__.lower()
+      method = getattr(obj, name, obj.visit_default)
+      self._cache[cls] = method
+    return method
+
+
+def patched_generate_tokens(original_tokens):
+    # type: (Iterable[TokenInfo]) -> Iterator[TokenInfo]
+    """
+    Fixes tokens yielded by `tokenize.generate_tokens` to handle more non-ASCII characters in identifiers.
+    Workaround for https://github.com/python/cpython/issues/68382.
+    Should only be used when tokenizing a string that is known to be valid syntax,
+    because it assumes that error tokens are not actually errors.
+    Combines groups of consecutive NAME, NUMBER, and/or ERRORTOKEN tokens into a single NAME token.
+    """
+    group = []  # type: List[tokenize.TokenInfo]
+    for tok in original_tokens:
+      if (
+          tok.type in (tokenize.NAME, tokenize.ERRORTOKEN, tokenize.NUMBER)
+          # Only combine tokens if they have no whitespace in between
+          and (not group or group[-1].end == tok.start)
+      ):
+        group.append(tok)
+      else:
+        for combined_token in combine_tokens(group):
+          yield combined_token
+        group = []
+        yield tok
+    for combined_token in combine_tokens(group):
+      yield combined_token
+
+def combine_tokens(group):
+    # type: (List[tokenize.TokenInfo]) -> List[tokenize.TokenInfo]
+    if not any(tok.type == tokenize.ERRORTOKEN for tok in group) or len({tok.line for tok in group}) != 1:
+      return group
+    return [
+      tokenize.TokenInfo(
+        type=tokenize.NAME,
+        string="".join(t.string for t in group),
+        start=group[0].start,
+        end=group[-1].end,
+        line=group[0].line,
+      )
+    ]
+
+
+def last_stmt(node):
+  # type: (ast.AST) -> ast.AST
+  """
+  If the given AST node contains multiple statements, return the last one.
+  Otherwise, just return the node.
+  """
+  child_stmts = [
+    child for child in iter_children_func(node)(node)
+    if is_stmt(child) or type(child).__name__ in (
+      "excepthandler",
+      "ExceptHandler",
+      "match_case",
+      "MatchCase",
+      "TryExcept",
+      "TryFinally",
+    )
+  ]
+  if child_stmts:
+    return last_stmt(child_stmts[-1])
+  return node
+
+
+
+@lru_cache(maxsize=None)
+def fstring_positions_work():
+  # type: () -> bool
+  """
+  The positions attached to nodes inside f-string FormattedValues have some bugs
+  that were fixed in Python 3.9.7 in https://github.com/python/cpython/pull/27729.
+  This checks for those bugs more concretely without relying on the Python version.
+  Specifically this checks:
+   - Values with a format spec or conversion
+   - Repeated (i.e. identical-looking) expressions
+   - f-strings implicitly concatenated over multiple lines.
+   - Multiline, triple-quoted f-strings.
+  """
+  source = """(
+    f"a {b}{b} c {d!r} e {f:g} h {i:{j}} k {l:{m:n}}"
+    f"a {b}{b} c {d!r} e {f:g} h {i:{j}} k {l:{m:n}}"
+    f"{x + y + z} {x} {y} {z} {z} {z!a} {z:z}"
+    f'''
+    {s} {t}
+    {u} {v}
+    '''
+  )"""
+  tree = ast.parse(source)
+  name_nodes = [node for node in ast.walk(tree) if isinstance(node, ast.Name)]
+  name_positions = [(node.lineno, node.col_offset) for node in name_nodes]
+  positions_are_unique = len(set(name_positions)) == len(name_positions)
+  correct_source_segments = all(
+    ast.get_source_segment(source, node) == node.id
+    for node in name_nodes
+  )
+  return positions_are_unique and correct_source_segments
+
+def annotate_fstring_nodes(tree):
+  # type: (ast.AST) -> None
+  """
+  Add a special attribute `_broken_positions` to nodes inside f-strings
+  if the lineno/col_offset cannot be trusted.
+  """
+  if sys.version_info >= (3, 12):
+    # f-strings were weirdly implemented until https://peps.python.org/pep-0701/
+    # In Python 3.12, inner nodes have sensible positions.
+    return
+  for joinedstr in walk(tree, include_joined_str=True):
+    if not isinstance(joinedstr, ast.JoinedStr):
+      continue
+    for part in joinedstr.values:
+      # The ast positions of the FormattedValues/Constant nodes span the full f-string, which is weird.
+      setattr(part, '_broken_positions', True)  # use setattr for mypy
+
+      if isinstance(part, ast.FormattedValue):
+        if not fstring_positions_work():
+          for child in walk(part.value):
+            setattr(child, '_broken_positions', True)
+
+        if part.format_spec:  # this is another JoinedStr
+          # Again, the standard positions span the full f-string.
+          setattr(part.format_spec, '_broken_positions', True)

venv/Lib/site-packages/asttokens/version.py

@@ -0,0 +1 @@
+__version__ = "3.0.0"

venv/Lib/site-packages/async_lru-2.0.5.dist-info/INSTALLER

@@ -0,0 +1 @@
+pip

venv/Lib/site-packages/async_lru-2.0.5.dist-info/LICENSE

@@ -0,0 +1,23 @@
+The MIT License
+
+Copyright (c) 2018 aio-libs team https://github.com/aio-libs/
+Copyright (c) 2017 Ocean S. A. https://ocean.io/
+Copyright (c) 2016-2017 WikiBusiness Corporation http://wikibusiness.org/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

venv/Lib/site-packages/async_lru-2.0.5.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.2
+Name: async-lru
+Version: 2.0.5
+Summary: Simple LRU cache for asyncio
+Home-page: https://github.com/aio-libs/async-lru
+Maintainer: aiohttp team <[email protected]>
+Maintainer-email: [email protected]
+License: MIT License
+Project-URL: Chat: Matrix, https://matrix.to/#/#aio-libs:matrix.org
+Project-URL: Chat: Matrix Space, https://matrix.to/#/#aio-libs-space:matrix.org
+Project-URL: CI: GitHub Actions, https://github.com/aio-libs/async-lru/actions
+Project-URL: GitHub: repo, https://github.com/aio-libs/async-lru
+Keywords: asyncio,lru,lru_cache
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: typing_extensions>=4.0.0; python_version < "3.11"
+
+async-lru
+=========
+
+:info: Simple lru cache for asyncio
+
+.. image:: https://github.com/aio-libs/async-lru/actions/workflows/ci-cd.yml/badge.svg?event=push
+   :target: https://github.com/aio-libs/async-lru/actions/workflows/ci-cd.yml?query=event:push
+   :alt: GitHub Actions CI/CD workflows status
+
+.. image:: https://img.shields.io/pypi/v/async-lru.svg?logo=Python&logoColor=white
+   :target: https://pypi.org/project/async-lru
+   :alt: async-lru @ PyPI
+
+.. image:: https://codecov.io/gh/aio-libs/async-lru/branch/master/graph/badge.svg
+    :target: https://codecov.io/gh/aio-libs/async-lru
+
+.. image:: https://img.shields.io/matrix/aio-libs:matrix.org?label=Discuss%20on%20Matrix%20at%20%23aio-libs%3Amatrix.org&logo=matrix&server_fqdn=matrix.org&style=flat
+   :target: https://matrix.to/#/%23aio-libs:matrix.org
+   :alt: Matrix Room — #aio-libs:matrix.org
+
+.. image:: https://img.shields.io/matrix/aio-libs-space:matrix.org?label=Discuss%20on%20Matrix%20at%20%23aio-libs-space%3Amatrix.org&logo=matrix&server_fqdn=matrix.org&style=flat
+   :target: https://matrix.to/#/%23aio-libs-space:matrix.org
+   :alt: Matrix Space — #aio-libs-space:matrix.org
+
+Installation
+------------
+
+.. code-block:: shell
+
+    pip install async-lru
+
+Usage
+-----
+
+This package is a port of Python's built-in `functools.lru_cache <https://docs.python.org/3/library/functools.html#functools.lru_cache>`_ function for `asyncio <https://docs.python.org/3/library/asyncio.html>`_. To better handle async behaviour, it also ensures multiple concurrent calls will only result in 1 call to the wrapped function, with all ``await``\s receiving the result of that call when it completes.
+
+.. code-block:: python
+
+    import asyncio
+
+    import aiohttp
+    from async_lru import alru_cache
+
+
+    @alru_cache(maxsize=32)
+    async def get_pep(num):
+        resource = 'http://www.python.org/dev/peps/pep-%04d/' % num
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.get(resource) as s:
+                    return await s.read()
+            except aiohttp.ClientError:
+                return 'Not Found'
+
+
+    async def main():
+        for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:
+            pep = await get_pep(n)
+            print(n, len(pep))
+
+        print(get_pep.cache_info())
+        # CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)
+
+        # closing is optional, but highly recommended
+        await get_pep.cache_close()
+
+
+    asyncio.run(main())
+
+
+TTL (time-to-live in seconds, expiration on timeout) is supported by accepting `ttl` configuration
+parameter (off by default):
+
+.. code-block:: python
+
+    @alru_cache(ttl=5)
+    async def func(arg):
+        return arg * 2
+
+
+The library supports explicit invalidation for specific function call by
+`cache_invalidate()`:
+
+.. code-block:: python
+
+    @alru_cache(ttl=5)
+    async def func(arg1, arg2):
+        return arg1 + arg2
+
+    func.cache_invalidate(1, arg2=2)
+
+The method returns `True` if corresponding arguments set was cached already, `False`
+otherwise.
+
+Thanks
+------
+
+The library was donated by `Ocean S.A. <https://ocean.io/>`_
+
+Thanks to the company for contribution.

venv/Lib/site-packages/async_lru-2.0.5.dist-info/RECORD

@@ -0,0 +1,9 @@
+async_lru-2.0.5.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+async_lru-2.0.5.dist-info/LICENSE,sha256=6mWXVnm8IJO-kl1SA1jkEJa9lv3e3uPpKRYKX6rc9XM,1226
+async_lru-2.0.5.dist-info/METADATA,sha256=8xQLHb4_Zr7AvNfM1kofHWX5JjNubmBnfJeicqq790I,4485
+async_lru-2.0.5.dist-info/RECORD,,
+async_lru-2.0.5.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+async_lru-2.0.5.dist-info/top_level.txt,sha256=nUy-F2tq_gf0YsQKIGqHmkS_XJxU_dQlINuXZIAHTsk,10
+async_lru/__init__.py,sha256=ebHg3Yib8ILqq0nNPRGG633b3kVb1ZaJFcZemYiSlEg,9425
+async_lru/__pycache__/__init__.cpython-312.pyc,,
+async_lru/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0

venv/Lib/site-packages/async_lru-2.0.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

venv/Lib/site-packages/async_lru-2.0.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+async_lru

venv/Lib/site-packages/async_lru/__init__.py

@@ -0,0 +1,346 @@
+import asyncio
+import dataclasses
+import sys
+from asyncio.coroutines import _is_coroutine  # type: ignore[attr-defined]
+from functools import _CacheInfo, _make_key, partial, partialmethod
+from typing import (
+    Any,
+    Callable,
+    Coroutine,
+    Generic,
+    Hashable,
+    Optional,
+    OrderedDict,
+    Set,
+    Type,
+    TypedDict,
+    TypeVar,
+    Union,
+    cast,
+    final,
+    overload,
+)
+
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+__version__ = "2.0.5"
+
+__all__ = ("alru_cache",)
+
+
+_T = TypeVar("_T")
+_R = TypeVar("_R")
+_Coro = Coroutine[Any, Any, _R]
+_CB = Callable[..., _Coro[_R]]
+_CBP = Union[_CB[_R], "partial[_Coro[_R]]", "partialmethod[_Coro[_R]]"]
+
+
+@final
+class _CacheParameters(TypedDict):
+    typed: bool
+    maxsize: Optional[int]
+    tasks: int
+    closed: bool
+
+
+@final
+@dataclasses.dataclass
+class _CacheItem(Generic[_R]):
+    fut: "asyncio.Future[_R]"
+    later_call: Optional[asyncio.Handle]
+
+    def cancel(self) -> None:
+        if self.later_call is not None:
+            self.later_call.cancel()
+            self.later_call = None
+
+
+@final
+class _LRUCacheWrapper(Generic[_R]):
+    def __init__(
+        self,
+        fn: _CB[_R],
+        maxsize: Optional[int],
+        typed: bool,
+        ttl: Optional[float],
+    ) -> None:
+        try:
+            self.__module__ = fn.__module__
+        except AttributeError:
+            pass
+        try:
+            self.__name__ = fn.__name__
+        except AttributeError:
+            pass
+        try:
+            self.__qualname__ = fn.__qualname__
+        except AttributeError:
+            pass
+        try:
+            self.__doc__ = fn.__doc__
+        except AttributeError:
+            pass
+        try:
+            self.__annotations__ = fn.__annotations__
+        except AttributeError:
+            pass
+        try:
+            self.__dict__.update(fn.__dict__)
+        except AttributeError:
+            pass
+        # set __wrapped__ last so we don't inadvertently copy it
+        # from the wrapped function when updating __dict__
+        self._is_coroutine = _is_coroutine
+        self.__wrapped__ = fn
+        self.__maxsize = maxsize
+        self.__typed = typed
+        self.__ttl = ttl
+        self.__cache: OrderedDict[Hashable, _CacheItem[_R]] = OrderedDict()
+        self.__closed = False
+        self.__hits = 0
+        self.__misses = 0
+        self.__tasks: Set["asyncio.Task[_R]"] = set()
+
+    def cache_invalidate(self, /, *args: Hashable, **kwargs: Any) -> bool:
+        key = _make_key(args, kwargs, self.__typed)
+
+        cache_item = self.__cache.pop(key, None)
+        if cache_item is None:
+            return False
+        else:
+            cache_item.cancel()
+            return True
+
+    def cache_clear(self) -> None:
+        self.__hits = 0
+        self.__misses = 0
+
+        for c in self.__cache.values():
+            if c.later_call:
+                c.later_call.cancel()
+        self.__cache.clear()
+        self.__tasks.clear()
+
+    async def cache_close(self, *, wait: bool = False) -> None:
+        self.__closed = True
+
+        tasks = list(self.__tasks)
+        if not tasks:
+            return
+
+        if not wait:
+            for task in tasks:
+                if not task.done():
+                    task.cancel()
+
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    def cache_info(self) -> _CacheInfo:
+        return _CacheInfo(
+            self.__hits,
+            self.__misses,
+            self.__maxsize,
+            len(self.__cache),
+        )
+
+    def cache_parameters(self) -> _CacheParameters:
+        return _CacheParameters(
+            maxsize=self.__maxsize,
+            typed=self.__typed,
+            tasks=len(self.__tasks),
+            closed=self.__closed,
+        )
+
+    def _cache_hit(self, key: Hashable) -> None:
+        self.__hits += 1
+        self.__cache.move_to_end(key)
+
+    def _cache_miss(self, key: Hashable) -> None:
+        self.__misses += 1
+
+    def _task_done_callback(
+        self, fut: "asyncio.Future[_R]", key: Hashable, task: "asyncio.Task[_R]"
+    ) -> None:
+        self.__tasks.discard(task)
+
+        if task.cancelled():
+            fut.cancel()
+            self.__cache.pop(key, None)
+            return
+
+        exc = task.exception()
+        if exc is not None:
+            fut.set_exception(exc)
+            self.__cache.pop(key, None)
+            return
+
+        cache_item = self.__cache.get(key)
+        if self.__ttl is not None and cache_item is not None:
+            loop = asyncio.get_running_loop()
+            cache_item.later_call = loop.call_later(
+                self.__ttl, self.__cache.pop, key, None
+            )
+
+        fut.set_result(task.result())
+
+    async def __call__(self, /, *fn_args: Any, **fn_kwargs: Any) -> _R:
+        if self.__closed:
+            raise RuntimeError(f"alru_cache is closed for {self}")
+
+        loop = asyncio.get_running_loop()
+
+        key = _make_key(fn_args, fn_kwargs, self.__typed)
+
+        cache_item = self.__cache.get(key)
+
+        if cache_item is not None:
+            self._cache_hit(key)
+            if not cache_item.fut.done():
+                return await asyncio.shield(cache_item.fut)
+
+            return cache_item.fut.result()
+
+        fut = loop.create_future()
+        coro = self.__wrapped__(*fn_args, **fn_kwargs)
+        task: asyncio.Task[_R] = loop.create_task(coro)
+        self.__tasks.add(task)
+        task.add_done_callback(partial(self._task_done_callback, fut, key))
+
+        self.__cache[key] = _CacheItem(fut, None)
+
+        if self.__maxsize is not None and len(self.__cache) > self.__maxsize:
+            dropped_key, cache_item = self.__cache.popitem(last=False)
+            cache_item.cancel()
+
+        self._cache_miss(key)
+        return await asyncio.shield(fut)
+
+    def __get__(
+        self, instance: _T, owner: Optional[Type[_T]]
+    ) -> Union[Self, "_LRUCacheWrapperInstanceMethod[_R, _T]"]:
+        if owner is None:
+            return self
+        else:
+            return _LRUCacheWrapperInstanceMethod(self, instance)
+
+
+@final
+class _LRUCacheWrapperInstanceMethod(Generic[_R, _T]):
+    def __init__(
+        self,
+        wrapper: _LRUCacheWrapper[_R],
+        instance: _T,
+    ) -> None:
+        try:
+            self.__module__ = wrapper.__module__
+        except AttributeError:
+            pass
+        try:
+            self.__name__ = wrapper.__name__
+        except AttributeError:
+            pass
+        try:
+            self.__qualname__ = wrapper.__qualname__
+        except AttributeError:
+            pass
+        try:
+            self.__doc__ = wrapper.__doc__
+        except AttributeError:
+            pass
+        try:
+            self.__annotations__ = wrapper.__annotations__
+        except AttributeError:
+            pass
+        try:
+            self.__dict__.update(wrapper.__dict__)
+        except AttributeError:
+            pass
+        # set __wrapped__ last so we don't inadvertently copy it
+        # from the wrapped function when updating __dict__
+        self._is_coroutine = _is_coroutine
+        self.__wrapped__ = wrapper.__wrapped__
+        self.__instance = instance
+        self.__wrapper = wrapper
+
+    def cache_invalidate(self, /, *args: Hashable, **kwargs: Any) -> bool:
+        return self.__wrapper.cache_invalidate(self.__instance, *args, **kwargs)
+
+    def cache_clear(self) -> None:
+        self.__wrapper.cache_clear()
+
+    async def cache_close(
+        self, *, cancel: bool = False, return_exceptions: bool = True
+    ) -> None:
+        await self.__wrapper.cache_close()
+
+    def cache_info(self) -> _CacheInfo:
+        return self.__wrapper.cache_info()
+
+    def cache_parameters(self) -> _CacheParameters:
+        return self.__wrapper.cache_parameters()
+
+    async def __call__(self, /, *fn_args: Any, **fn_kwargs: Any) -> _R:
+        return await self.__wrapper(self.__instance, *fn_args, **fn_kwargs)
+
+
+def _make_wrapper(
+    maxsize: Optional[int],
+    typed: bool,
+    ttl: Optional[float] = None,
+) -> Callable[[_CBP[_R]], _LRUCacheWrapper[_R]]:
+    def wrapper(fn: _CBP[_R]) -> _LRUCacheWrapper[_R]:
+        origin = fn
+
+        while isinstance(origin, (partial, partialmethod)):
+            origin = origin.func
+
+        if not asyncio.iscoroutinefunction(origin):
+            raise RuntimeError(f"Coroutine function is required, got {fn!r}")
+
+        # functools.partialmethod support
+        if hasattr(fn, "_make_unbound_method"):
+            fn = fn._make_unbound_method()
+
+        return _LRUCacheWrapper(cast(_CB[_R], fn), maxsize, typed, ttl)
+
+    return wrapper
+
+
+@overload
+def alru_cache(
+    maxsize: Optional[int] = 128,
+    typed: bool = False,
+    *,
+    ttl: Optional[float] = None,
+) -> Callable[[_CBP[_R]], _LRUCacheWrapper[_R]]:
+    ...
+
+
+@overload
+def alru_cache(
+    maxsize: _CBP[_R],
+    /,
+) -> _LRUCacheWrapper[_R]:
+    ...
+
+
+def alru_cache(
+    maxsize: Union[Optional[int], _CBP[_R]] = 128,
+    typed: bool = False,
+    *,
+    ttl: Optional[float] = None,
+) -> Union[Callable[[_CBP[_R]], _LRUCacheWrapper[_R]], _LRUCacheWrapper[_R]]:
+    if maxsize is None or isinstance(maxsize, int):
+        return _make_wrapper(maxsize, typed, ttl)
+    else:
+        fn = cast(_CB[_R], maxsize)
+
+        if callable(fn) or hasattr(fn, "_make_unbound_method"):
+            return _make_wrapper(128, False, None)(fn)
+
+        raise NotImplementedError(f"{fn!r} decorating is not supported")

venv/Lib/site-packages/attr/__init__.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+
+"""
+Classes Without Boilerplate
+"""
+
+from functools import partial
+from typing import Callable, Literal, Protocol
+
+from . import converters, exceptions, filters, setters, validators
+from ._cmp import cmp_using
+from ._config import get_run_validators, set_run_validators
+from ._funcs import asdict, assoc, astuple, has, resolve_types
+from ._make import (
+    NOTHING,
+    Attribute,
+    Converter,
+    Factory,
+    _Nothing,
+    attrib,
+    attrs,
+    evolve,
+    fields,
+    fields_dict,
+    make_class,
+    validate,
+)
+from ._next_gen import define, field, frozen, mutable
+from ._version_info import VersionInfo
+
+
+s = attributes = attrs
+ib = attr = attrib
+dataclass = partial(attrs, auto_attribs=True)  # happy Easter ;)
+
+
+class AttrsInstance(Protocol):
+    pass
+
+
+NothingType = Literal[_Nothing.NOTHING]
+
+__all__ = [
+    "NOTHING",
+    "Attribute",
+    "AttrsInstance",
+    "Converter",
+    "Factory",
+    "NothingType",
+    "asdict",
+    "assoc",
+    "astuple",
+    "attr",
+    "attrib",
+    "attributes",
+    "attrs",
+    "cmp_using",
+    "converters",
+    "define",
+    "evolve",
+    "exceptions",
+    "field",
+    "fields",
+    "fields_dict",
+    "filters",
+    "frozen",
+    "get_run_validators",
+    "has",
+    "ib",
+    "make_class",
+    "mutable",
+    "resolve_types",
+    "s",
+    "set_run_validators",
+    "setters",
+    "validate",
+    "validators",
+]
+
+
+def _make_getattr(mod_name: str) -> Callable:
+    """
+    Create a metadata proxy for packaging information that uses *mod_name* in
+    its warnings and errors.
+    """
+
+    def __getattr__(name: str) -> str:
+        if name not in ("__version__", "__version_info__"):
+            msg = f"module {mod_name} has no attribute {name}"
+            raise AttributeError(msg)
+
+        from importlib.metadata import metadata
+
+        meta = metadata("attrs")
+
+        if name == "__version_info__":
+            return VersionInfo._from_version_string(meta["version"])
+
+        return meta["version"]
+
+    return __getattr__
+
+
+__getattr__ = _make_getattr(__name__)

venv/Lib/site-packages/attr/__init__.pyi

@@ -0,0 +1,389 @@
+import enum
+import sys
+
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Literal,
+    Mapping,
+    Protocol,
+    Sequence,
+    TypeVar,
+    overload,
+)
+
+# `import X as X` is required to make these public
+from . import converters as converters
+from . import exceptions as exceptions
+from . import filters as filters
+from . import setters as setters
+from . import validators as validators
+from ._cmp import cmp_using as cmp_using
+from ._typing_compat import AttrsInstance_
+from ._version_info import VersionInfo
+from attrs import (
+    define as define,
+    field as field,
+    mutable as mutable,
+    frozen as frozen,
+    _EqOrderType,
+    _ValidatorType,
+    _ConverterType,
+    _ReprArgType,
+    _OnSetAttrType,
+    _OnSetAttrArgType,
+    _FieldTransformer,
+    _ValidatorArgType,
+)
+
+if sys.version_info >= (3, 10):
+    from typing import TypeGuard, TypeAlias
+else:
+    from typing_extensions import TypeGuard, TypeAlias
+
+if sys.version_info >= (3, 11):
+    from typing import dataclass_transform
+else:
+    from typing_extensions import dataclass_transform
+
+__version__: str
+__version_info__: VersionInfo
+__title__: str
+__description__: str
+__url__: str
+__uri__: str
+__author__: str
+__email__: str
+__license__: str
+__copyright__: str
+
+_T = TypeVar("_T")
+_C = TypeVar("_C", bound=type)
+
+_FilterType = Callable[["Attribute[_T]", _T], bool]
+
+# We subclass this here to keep the protocol's qualified name clean.
+class AttrsInstance(AttrsInstance_, Protocol):
+    pass
+
+_A = TypeVar("_A", bound=type[AttrsInstance])
+
+class _Nothing(enum.Enum):
+    NOTHING = enum.auto()
+
+NOTHING = _Nothing.NOTHING
+NothingType: TypeAlias = Literal[_Nothing.NOTHING]
+
+# NOTE: Factory lies about its return type to make this possible:
+# `x: List[int] # = Factory(list)`
+# Work around mypy issue #4554 in the common case by using an overload.
+
+@overload
+def Factory(factory: Callable[[], _T]) -> _T: ...
+@overload
+def Factory(
+    factory: Callable[[Any], _T],
+    takes_self: Literal[True],
+) -> _T: ...
+@overload
+def Factory(
+    factory: Callable[[], _T],
+    takes_self: Literal[False],
+) -> _T: ...
+
+In = TypeVar("In")
+Out = TypeVar("Out")
+
+class Converter(Generic[In, Out]):
+    @overload
+    def __init__(self, converter: Callable[[In], Out]) -> None: ...
+    @overload
+    def __init__(
+        self,
+        converter: Callable[[In, AttrsInstance, Attribute], Out],
+        *,
+        takes_self: Literal[True],
+        takes_field: Literal[True],
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        converter: Callable[[In, Attribute], Out],
+        *,
+        takes_field: Literal[True],
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        converter: Callable[[In, AttrsInstance], Out],
+        *,
+        takes_self: Literal[True],
+    ) -> None: ...
+
+class Attribute(Generic[_T]):
+    name: str
+    default: _T | None
+    validator: _ValidatorType[_T] | None
+    repr: _ReprArgType
+    cmp: _EqOrderType
+    eq: _EqOrderType
+    order: _EqOrderType
+    hash: bool | None
+    init: bool
+    converter: Converter | None
+    metadata: dict[Any, Any]
+    type: type[_T] | None
+    kw_only: bool
+    on_setattr: _OnSetAttrType
+    alias: str | None
+
+    def evolve(self, **changes: Any) -> "Attribute[Any]": ...
+
+# NOTE: We had several choices for the annotation to use for type arg:
+# 1) Type[_T]
+#   - Pros: Handles simple cases correctly
+#   - Cons: Might produce less informative errors in the case of conflicting
+#     TypeVars e.g. `attr.ib(default='bad', type=int)`
+# 2) Callable[..., _T]
+#   - Pros: Better error messages than #1 for conflicting TypeVars
+#   - Cons: Terrible error messages for validator checks.
+#   e.g. attr.ib(type=int, validator=validate_str)
+#        -> error: Cannot infer function type argument
+# 3) type (and do all of the work in the mypy plugin)
+#   - Pros: Simple here, and we could customize the plugin with our own errors.
+#   - Cons: Would need to write mypy plugin code to handle all the cases.
+# We chose option #1.
+
+# `attr` lies about its return type to make the following possible:
+#     attr()    -> Any
+#     attr(8)   -> int
+#     attr(validator=<some callable>)  -> Whatever the callable expects.
+# This makes this type of assignments possible:
+#     x: int = attr(8)
+#
+# This form catches explicit None or no default but with no other arguments
+# returns Any.
+@overload
+def attrib(
+    default: None = ...,
+    validator: None = ...,
+    repr: _ReprArgType = ...,
+    cmp: _EqOrderType | None = ...,
+    hash: bool | None = ...,
+    init: bool = ...,
+    metadata: Mapping[Any, Any] | None = ...,
+    type: None = ...,
+    converter: None = ...,
+    factory: None = ...,
+    kw_only: bool = ...,
+    eq: _EqOrderType | None = ...,
+    order: _EqOrderType | None = ...,
+    on_setattr: _OnSetAttrArgType | None = ...,
+    alias: str | None = ...,
+) -> Any: ...
+
+# This form catches an explicit None or no default and infers the type from the
+# other arguments.
+@overload
+def attrib(
+    default: None = ...,
+    validator: _ValidatorArgType[_T] | None = ...,
+    repr: _ReprArgType = ...,
+    cmp: _EqOrderType | None = ...,
+    hash: bool | None = ...,
+    init: bool = ...,
+    metadata: Mapping[Any, Any] | None = ...,
+    type: type[_T] | None = ...,
+    converter: _ConverterType
+    | list[_ConverterType]
+    | tuple[_ConverterType]
+    | None = ...,
+    factory: Callable[[], _T] | None = ...,
+    kw_only: bool = ...,
+    eq: _EqOrderType | None = ...,
+    order: _EqOrderType | None = ...,
+    on_setattr: _OnSetAttrArgType | None = ...,
+    alias: str | None = ...,
+) -> _T: ...
+
+# This form catches an explicit default argument.
+@overload
+def attrib(
+    default: _T,
+    validator: _ValidatorArgType[_T] | None = ...,
+    repr: _ReprArgType = ...,
+    cmp: _EqOrderType | None = ...,
+    hash: bool | None = ...,
+    init: bool = ...,
+    metadata: Mapping[Any, Any] | None = ...,
+    type: type[_T] | None = ...,
+    converter: _ConverterType
+    | list[_ConverterType]
+    | tuple[_ConverterType]
+    | None = ...,
+    factory: Callable[[], _T] | None = ...,
+    kw_only: bool = ...,
+    eq: _EqOrderType | None = ...,
+    order: _EqOrderType | None = ...,
+    on_setattr: _OnSetAttrArgType | None = ...,
+    alias: str | None = ...,
+) -> _T: ...
+
+# This form covers type=non-Type: e.g. forward references (str), Any
+@overload
+def attrib(
+    default: _T | None = ...,
+    validator: _ValidatorArgType[_T] | None = ...,
+    repr: _ReprArgType = ...,
+    cmp: _EqOrderType | None = ...,
+    hash: bool | None = ...,
+    init: bool = ...,
+    metadata: Mapping[Any, Any] | None = ...,
+    type: object = ...,
+    converter: _ConverterType
+    | list[_ConverterType]
+    | tuple[_ConverterType]
+    | None = ...,
+    factory: Callable[[], _T] | None = ...,
+    kw_only: bool = ...,
+    eq: _EqOrderType | None = ...,
+    order: _EqOrderType | None = ...,
+    on_setattr: _OnSetAttrArgType | None = ...,
+    alias: str | None = ...,
+) -> Any: ...
+@overload
+@dataclass_transform(order_default=True, field_specifiers=(attrib, field))
+def attrs(
+    maybe_cls: _C,
+    these: dict[str, Any] | None = ...,
+    repr_ns: str | None = ...,
+    repr: bool = ...,
+    cmp: _EqOrderType | None = ...,
+    hash: bool | None = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+    auto_exc: bool = ...,
+    eq: _EqOrderType | None = ...,
+    order: _EqOrderType | None = ...,
+    auto_detect: bool = ...,
+    collect_by_mro: bool = ...,
+    getstate_setstate: bool | None = ...,
+    on_setattr: _OnSetAttrArgType | None = ...,
+    field_transformer: _FieldTransformer | None = ...,
+    match_args: bool = ...,
+    unsafe_hash: bool | None = ...,
+) -> _C: ...
+@overload
+@dataclass_transform(order_default=True, field_specifiers=(attrib, field))
+def attrs(
+    maybe_cls: None = ...,
+    these: dict[str, Any] | None = ...,
+    repr_ns: str | None = ...,
+    repr: bool = ...,
+    cmp: _EqOrderType | None = ...,
+    hash: bool | None = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+    auto_exc: bool = ...,
+    eq: _EqOrderType | None = ...,
+    order: _EqOrderType | None = ...,
+    auto_detect: bool = ...,
+    collect_by_mro: bool = ...,
+    getstate_setstate: bool | None = ...,
+    on_setattr: _OnSetAttrArgType | None = ...,
+    field_transformer: _FieldTransformer | None = ...,
+    match_args: bool = ...,
+    unsafe_hash: bool | None = ...,
+) -> Callable[[_C], _C]: ...
+def fields(cls: type[AttrsInstance]) -> Any: ...
+def fields_dict(cls: type[AttrsInstance]) -> dict[str, Attribute[Any]]: ...
+def validate(inst: AttrsInstance) -> None: ...
+def resolve_types(
+    cls: _A,
+    globalns: dict[str, Any] | None = ...,
+    localns: dict[str, Any] | None = ...,
+    attribs: list[Attribute[Any]] | None = ...,
+    include_extras: bool = ...,
+) -> _A: ...
+
+# TODO: add support for returning a proper attrs class from the mypy plugin
+# we use Any instead of _CountingAttr so that e.g. `make_class('Foo',
+# [attr.ib()])` is valid
+def make_class(
+    name: str,
+    attrs: list[str] | tuple[str, ...] | dict[str, Any],
+    bases: tuple[type, ...] = ...,
+    class_body: dict[str, Any] | None = ...,
+    repr_ns: str | None = ...,
+    repr: bool = ...,
+    cmp: _EqOrderType | None = ...,
+    hash: bool | None = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+    auto_exc: bool = ...,
+    eq: _EqOrderType | None = ...,
+    order: _EqOrderType | None = ...,
+    collect_by_mro: bool = ...,
+    on_setattr: _OnSetAttrArgType | None = ...,
+    field_transformer: _FieldTransformer | None = ...,
+) -> type: ...
+
+# _funcs --
+
+# TODO: add support for returning TypedDict from the mypy plugin
+# FIXME: asdict/astuple do not honor their factory args. Waiting on one of
+# these:
+# https://github.com/python/mypy/issues/4236
+# https://github.com/python/typing/issues/253
+# XXX: remember to fix attrs.asdict/astuple too!
+def asdict(
+    inst: AttrsInstance,
+    recurse: bool = ...,
+    filter: _FilterType[Any] | None = ...,
+    dict_factory: type[Mapping[Any, Any]] = ...,
+    retain_collection_types: bool = ...,
+    value_serializer: Callable[[type, Attribute[Any], Any], Any] | None = ...,
+    tuple_keys: bool | None = ...,
+) -> dict[str, Any]: ...
+
+# TODO: add support for returning NamedTuple from the mypy plugin
+def astuple(
+    inst: AttrsInstance,
+    recurse: bool = ...,
+    filter: _FilterType[Any] | None = ...,
+    tuple_factory: type[Sequence[Any]] = ...,
+    retain_collection_types: bool = ...,
+) -> tuple[Any, ...]: ...
+def has(cls: type) -> TypeGuard[type[AttrsInstance]]: ...
+def assoc(inst: _T, **changes: Any) -> _T: ...
+def evolve(inst: _T, **changes: Any) -> _T: ...
+
+# _config --
+
+def set_run_validators(run: bool) -> None: ...
+def get_run_validators() -> bool: ...
+
+# aliases --
+
+s = attributes = attrs
+ib = attr = attrib
+dataclass = attrs  # Technically, partial(attrs, auto_attribs=True) ;)

venv/Lib/site-packages/attr/_cmp.py

@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: MIT
+
+
+import functools
+import types
+
+from ._make import __ne__
+
+
+_operation_names = {"eq": "==", "lt": "<", "le": "<=", "gt": ">", "ge": ">="}
+
+
+def cmp_using(
+    eq=None,
+    lt=None,
+    le=None,
+    gt=None,
+    ge=None,
+    require_same_type=True,
+    class_name="Comparable",
+):
+    """
+    Create a class that can be passed into `attrs.field`'s ``eq``, ``order``,
+    and ``cmp`` arguments to customize field comparison.
+
+    The resulting class will have a full set of ordering methods if at least
+    one of ``{lt, le, gt, ge}`` and ``eq``  are provided.
+
+    Args:
+        eq (typing.Callable | None):
+            Callable used to evaluate equality of two objects.
+
+        lt (typing.Callable | None):
+            Callable used to evaluate whether one object is less than another
+            object.
+
+        le (typing.Callable | None):
+            Callable used to evaluate whether one object is less than or equal
+            to another object.
+
+        gt (typing.Callable | None):
+            Callable used to evaluate whether one object is greater than
+            another object.
+
+        ge (typing.Callable | None):
+            Callable used to evaluate whether one object is greater than or
+            equal to another object.
+
+        require_same_type (bool):
+            When `True`, equality and ordering methods will return
+            `NotImplemented` if objects are not of the same type.
+
+        class_name (str | None): Name of class. Defaults to "Comparable".
+
+    See `comparison` for more details.
+
+    .. versionadded:: 21.1.0
+    """
+
+    body = {
+        "__slots__": ["value"],
+        "__init__": _make_init(),
+        "_requirements": [],
+        "_is_comparable_to": _is_comparable_to,
+    }
+
+    # Add operations.
+    num_order_functions = 0
+    has_eq_function = False
+
+    if eq is not None:
+        has_eq_function = True
+        body["__eq__"] = _make_operator("eq", eq)
+        body["__ne__"] = __ne__
+
+    if lt is not None:
+        num_order_functions += 1
+        body["__lt__"] = _make_operator("lt", lt)
+
+    if le is not None:
+        num_order_functions += 1
+        body["__le__"] = _make_operator("le", le)
+
+    if gt is not None:
+        num_order_functions += 1
+        body["__gt__"] = _make_operator("gt", gt)
+
+    if ge is not None:
+        num_order_functions += 1
+        body["__ge__"] = _make_operator("ge", ge)
+
+    type_ = types.new_class(
+        class_name, (object,), {}, lambda ns: ns.update(body)
+    )
+
+    # Add same type requirement.
+    if require_same_type:
+        type_._requirements.append(_check_same_type)
+
+    # Add total ordering if at least one operation was defined.
+    if 0 < num_order_functions < 4:
+        if not has_eq_function:
+            # functools.total_ordering requires __eq__ to be defined,
+            # so raise early error here to keep a nice stack.
+            msg = "eq must be define is order to complete ordering from lt, le, gt, ge."
+            raise ValueError(msg)
+        type_ = functools.total_ordering(type_)
+
+    return type_
+
+
+def _make_init():
+    """
+    Create __init__ method.
+    """
+
+    def __init__(self, value):
+        """
+        Initialize object with *value*.
+        """
+        self.value = value
+
+    return __init__
+
+
+def _make_operator(name, func):
+    """
+    Create operator method.
+    """
+
+    def method(self, other):
+        if not self._is_comparable_to(other):
+            return NotImplemented
+
+        result = func(self.value, other.value)
+        if result is NotImplemented:
+            return NotImplemented
+
+        return result
+
+    method.__name__ = f"__{name}__"
+    method.__doc__ = (
+        f"Return a {_operation_names[name]} b.  Computed by attrs."
+    )
+
+    return method
+
+
+def _is_comparable_to(self, other):
+    """
+    Check whether `other` is comparable to `self`.
+    """
+    return all(func(self, other) for func in self._requirements)
+
+
+def _check_same_type(self, other):
+    """
+    Return True if *self* and *other* are of the same type, False otherwise.
+    """
+    return other.value.__class__ is self.value.__class__

venv/Lib/site-packages/attr/_cmp.pyi

@@ -0,0 +1,13 @@
+from typing import Any, Callable
+
+_CompareWithType = Callable[[Any, Any], bool]
+
+def cmp_using(
+    eq: _CompareWithType | None = ...,
+    lt: _CompareWithType | None = ...,
+    le: _CompareWithType | None = ...,
+    gt: _CompareWithType | None = ...,
+    ge: _CompareWithType | None = ...,
+    require_same_type: bool = ...,
+    class_name: str = ...,
+) -> type: ...

venv/Lib/site-packages/attr/_compat.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: MIT
+
+import inspect
+import platform
+import sys
+import threading
+
+from collections.abc import Mapping, Sequence  # noqa: F401
+from typing import _GenericAlias
+
+
+PYPY = platform.python_implementation() == "PyPy"
+PY_3_9_PLUS = sys.version_info[:2] >= (3, 9)
+PY_3_10_PLUS = sys.version_info[:2] >= (3, 10)
+PY_3_11_PLUS = sys.version_info[:2] >= (3, 11)
+PY_3_12_PLUS = sys.version_info[:2] >= (3, 12)
+PY_3_13_PLUS = sys.version_info[:2] >= (3, 13)
+PY_3_14_PLUS = sys.version_info[:2] >= (3, 14)
+
+
+if PY_3_14_PLUS:  # pragma: no cover
+    import annotationlib
+
+    _get_annotations = annotationlib.get_annotations
+
+else:
+
+    def _get_annotations(cls):
+        """
+        Get annotations for *cls*.
+        """
+        return cls.__dict__.get("__annotations__", {})
+
+
+class _AnnotationExtractor:
+    """
+    Extract type annotations from a callable, returning None whenever there
+    is none.
+    """
+
+    __slots__ = ["sig"]
+
+    def __init__(self, callable):
+        try:
+            self.sig = inspect.signature(callable)
+        except (ValueError, TypeError):  # inspect failed
+            self.sig = None
+
+    def get_first_param_type(self):
+        """
+        Return the type annotation of the first argument if it's not empty.
+        """
+        if not self.sig:
+            return None
+
+        params = list(self.sig.parameters.values())
+        if params and params[0].annotation is not inspect.Parameter.empty:
+            return params[0].annotation
+
+        return None
+
+    def get_return_type(self):
+        """
+        Return the return type if it's not empty.
+        """
+        if (
+            self.sig
+            and self.sig.return_annotation is not inspect.Signature.empty
+        ):
+            return self.sig.return_annotation
+
+        return None
+
+
+# Thread-local global to track attrs instances which are already being repr'd.
+# This is needed because there is no other (thread-safe) way to pass info
+# about the instances that are already being repr'd through the call stack
+# in order to ensure we don't perform infinite recursion.
+#
+# For instance, if an instance contains a dict which contains that instance,
+# we need to know that we're already repr'ing the outside instance from within
+# the dict's repr() call.
+#
+# This lives here rather than in _make.py so that the functions in _make.py
+# don't have a direct reference to the thread-local in their globals dict.
+# If they have such a reference, it breaks cloudpickle.
+repr_context = threading.local()
+
+
+def get_generic_base(cl):
+    """If this is a generic class (A[str]), return the generic base for it."""
+    if cl.__class__ is _GenericAlias:
+        return cl.__origin__
+    return None

venv/Lib/site-packages/attr/_config.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+
+__all__ = ["get_run_validators", "set_run_validators"]
+
+_run_validators = True
+
+
+def set_run_validators(run):
+    """
+    Set whether or not validators are run.  By default, they are run.
+
+    .. deprecated:: 21.3.0 It will not be removed, but it also will not be
+        moved to new ``attrs`` namespace. Use `attrs.validators.set_disabled()`
+        instead.
+    """
+    if not isinstance(run, bool):
+        msg = "'run' must be bool."
+        raise TypeError(msg)
+    global _run_validators
+    _run_validators = run
+
+
+def get_run_validators():
+    """
+    Return whether or not validators are run.
+
+    .. deprecated:: 21.3.0 It will not be removed, but it also will not be
+        moved to new ``attrs`` namespace. Use `attrs.validators.get_disabled()`
+        instead.
+    """
+    return _run_validators

venv/Lib/site-packages/attr/_funcs.py

@@ -0,0 +1,468 @@
+# SPDX-License-Identifier: MIT
+
+
+import copy
+
+from ._compat import PY_3_9_PLUS, get_generic_base
+from ._make import _OBJ_SETATTR, NOTHING, fields
+from .exceptions import AttrsAttributeNotFoundError
+
+
+def asdict(
+    inst,
+    recurse=True,
+    filter=None,
+    dict_factory=dict,
+    retain_collection_types=False,
+    value_serializer=None,
+):
+    """
+    Return the *attrs* attribute values of *inst* as a dict.
+
+    Optionally recurse into other *attrs*-decorated classes.
+
+    Args:
+        inst: Instance of an *attrs*-decorated class.
+
+        recurse (bool): Recurse into classes that are also *attrs*-decorated.
+
+        filter (~typing.Callable):
+            A callable whose return code determines whether an attribute or
+            element is included (`True`) or dropped (`False`).  Is called with
+            the `attrs.Attribute` as the first argument and the value as the
+            second argument.
+
+        dict_factory (~typing.Callable):
+            A callable to produce dictionaries from.  For example, to produce
+            ordered dictionaries instead of normal Python dictionaries, pass in
+            ``collections.OrderedDict``.
+
+        retain_collection_types (bool):
+            Do not convert to `list` when encountering an attribute whose type
+            is `tuple` or `set`.  Only meaningful if *recurse* is `True`.
+
+        value_serializer (typing.Callable | None):
+            A hook that is called for every attribute or dict key/value.  It
+            receives the current instance, field and value and must return the
+            (updated) value.  The hook is run *after* the optional *filter* has
+            been applied.
+
+    Returns:
+        Return type of *dict_factory*.
+
+    Raises:
+        attrs.exceptions.NotAnAttrsClassError:
+            If *cls* is not an *attrs* class.
+
+    ..  versionadded:: 16.0.0 *dict_factory*
+    ..  versionadded:: 16.1.0 *retain_collection_types*
+    ..  versionadded:: 20.3.0 *value_serializer*
+    ..  versionadded:: 21.3.0
+        If a dict has a collection for a key, it is serialized as a tuple.
+    """
+    attrs = fields(inst.__class__)
+    rv = dict_factory()
+    for a in attrs:
+        v = getattr(inst, a.name)
+        if filter is not None and not filter(a, v):
+            continue
+
+        if value_serializer is not None:
+            v = value_serializer(inst, a, v)
+
+        if recurse is True:
+            if has(v.__class__):
+                rv[a.name] = asdict(
+                    v,
+                    recurse=True,
+                    filter=filter,
+                    dict_factory=dict_factory,
+                    retain_collection_types=retain_collection_types,
+                    value_serializer=value_serializer,
+                )
+            elif isinstance(v, (tuple, list, set, frozenset)):
+                cf = v.__class__ if retain_collection_types is True else list
+                items = [
+                    _asdict_anything(
+                        i,
+                        is_key=False,
+                        filter=filter,
+                        dict_factory=dict_factory,
+                        retain_collection_types=retain_collection_types,
+                        value_serializer=value_serializer,
+                    )
+                    for i in v
+                ]
+                try:
+                    rv[a.name] = cf(items)
+                except TypeError:
+                    if not issubclass(cf, tuple):
+                        raise
+                    # Workaround for TypeError: cf.__new__() missing 1 required
+                    # positional argument (which appears, for a namedturle)
+                    rv[a.name] = cf(*items)
+            elif isinstance(v, dict):
+                df = dict_factory
+                rv[a.name] = df(
+                    (
+                        _asdict_anything(
+                            kk,
+                            is_key=True,
+                            filter=filter,
+                            dict_factory=df,
+                            retain_collection_types=retain_collection_types,
+                            value_serializer=value_serializer,
+                        ),
+                        _asdict_anything(
+                            vv,
+                            is_key=False,
+                            filter=filter,
+                            dict_factory=df,
+                            retain_collection_types=retain_collection_types,
+                            value_serializer=value_serializer,
+                        ),
+                    )
+                    for kk, vv in v.items()
+                )
+            else:
+                rv[a.name] = v
+        else:
+            rv[a.name] = v
+    return rv
+
+
+def _asdict_anything(
+    val,
+    is_key,
+    filter,
+    dict_factory,
+    retain_collection_types,
+    value_serializer,
+):
+    """
+    ``asdict`` only works on attrs instances, this works on anything.
+    """
+    if getattr(val.__class__, "__attrs_attrs__", None) is not None:
+        # Attrs class.
+        rv = asdict(
+            val,
+            recurse=True,
+            filter=filter,
+            dict_factory=dict_factory,
+            retain_collection_types=retain_collection_types,
+            value_serializer=value_serializer,
+        )
+    elif isinstance(val, (tuple, list, set, frozenset)):
+        if retain_collection_types is True:
+            cf = val.__class__
+        elif is_key:
+            cf = tuple
+        else:
+            cf = list
+
+        rv = cf(
+            [
+                _asdict_anything(
+                    i,
+                    is_key=False,
+                    filter=filter,
+                    dict_factory=dict_factory,
+                    retain_collection_types=retain_collection_types,
+                    value_serializer=value_serializer,
+                )
+                for i in val
+            ]
+        )
+    elif isinstance(val, dict):
+        df = dict_factory
+        rv = df(
+            (
+                _asdict_anything(
+                    kk,
+                    is_key=True,
+                    filter=filter,
+                    dict_factory=df,
+                    retain_collection_types=retain_collection_types,
+                    value_serializer=value_serializer,
+                ),
+                _asdict_anything(
+                    vv,
+                    is_key=False,
+                    filter=filter,
+                    dict_factory=df,
+                    retain_collection_types=retain_collection_types,
+                    value_serializer=value_serializer,
+                ),
+            )
+            for kk, vv in val.items()
+        )
+    else:
+        rv = val
+        if value_serializer is not None:
+            rv = value_serializer(None, None, rv)
+
+    return rv
+
+
+def astuple(
+    inst,
+    recurse=True,
+    filter=None,
+    tuple_factory=tuple,
+    retain_collection_types=False,
+):
+    """
+    Return the *attrs* attribute values of *inst* as a tuple.
+
+    Optionally recurse into other *attrs*-decorated classes.
+
+    Args:
+        inst: Instance of an *attrs*-decorated class.
+
+        recurse (bool):
+            Recurse into classes that are also *attrs*-decorated.
+
+        filter (~typing.Callable):
+            A callable whose return code determines whether an attribute or
+            element is included (`True`) or dropped (`False`).  Is called with
+            the `attrs.Attribute` as the first argument and the value as the
+            second argument.
+
+        tuple_factory (~typing.Callable):
+            A callable to produce tuples from. For example, to produce lists
+            instead of tuples.
+
+        retain_collection_types (bool):
+            Do not convert to `list` or `dict` when encountering an attribute
+            which type is `tuple`, `dict` or `set`. Only meaningful if
+            *recurse* is `True`.
+
+    Returns:
+        Return type of *tuple_factory*
+
+    Raises:
+        attrs.exceptions.NotAnAttrsClassError:
+            If *cls* is not an *attrs* class.
+
+    ..  versionadded:: 16.2.0
+    """
+    attrs = fields(inst.__class__)
+    rv = []
+    retain = retain_collection_types  # Very long. :/
+    for a in attrs:
+        v = getattr(inst, a.name)
+        if filter is not None and not filter(a, v):
+            continue
+        if recurse is True:
+            if has(v.__class__):
+                rv.append(
+                    astuple(
+                        v,
+                        recurse=True,
+                        filter=filter,
+                        tuple_factory=tuple_factory,
+                        retain_collection_types=retain,
+                    )
+                )
+            elif isinstance(v, (tuple, list, set, frozenset)):
+                cf = v.__class__ if retain is True else list
+                items = [
+                    (
+                        astuple(
+                            j,
+                            recurse=True,
+                            filter=filter,
+                            tuple_factory=tuple_factory,
+                            retain_collection_types=retain,
+                        )
+                        if has(j.__class__)
+                        else j
+                    )
+                    for j in v
+                ]
+                try:
+                    rv.append(cf(items))
+                except TypeError:
+                    if not issubclass(cf, tuple):
+                        raise
+                    # Workaround for TypeError: cf.__new__() missing 1 required
+                    # positional argument (which appears, for a namedturle)
+                    rv.append(cf(*items))
+            elif isinstance(v, dict):
+                df = v.__class__ if retain is True else dict
+                rv.append(
+                    df(
+                        (
+                            (
+                                astuple(
+                                    kk,
+                                    tuple_factory=tuple_factory,
+                                    retain_collection_types=retain,
+                                )
+                                if has(kk.__class__)
+                                else kk
+                            ),
+                            (
+                                astuple(
+                                    vv,
+                                    tuple_factory=tuple_factory,
+                                    retain_collection_types=retain,
+                                )
+                                if has(vv.__class__)
+                                else vv
+                            ),
+                        )
+                        for kk, vv in v.items()
+                    )
+                )
+            else:
+                rv.append(v)
+        else:
+            rv.append(v)
+
+    return rv if tuple_factory is list else tuple_factory(rv)
+
+
+def has(cls):
+    """
+    Check whether *cls* is a class with *attrs* attributes.
+
+    Args:
+        cls (type): Class to introspect.
+
+    Raises:
+        TypeError: If *cls* is not a class.
+
+    Returns:
+        bool:
+    """
+    attrs = getattr(cls, "__attrs_attrs__", None)
+    if attrs is not None:
+        return True
+
+    # No attrs, maybe it's a specialized generic (A[str])?
+    generic_base = get_generic_base(cls)
+    if generic_base is not None:
+        generic_attrs = getattr(generic_base, "__attrs_attrs__", None)
+        if generic_attrs is not None:
+            # Stick it on here for speed next time.
+            cls.__attrs_attrs__ = generic_attrs
+        return generic_attrs is not None
+    return False
+
+
+def assoc(inst, **changes):
+    """
+    Copy *inst* and apply *changes*.
+
+    This is different from `evolve` that applies the changes to the arguments
+    that create the new instance.
+
+    `evolve`'s behavior is preferable, but there are `edge cases`_ where it
+    doesn't work. Therefore `assoc` is deprecated, but will not be removed.
+
+    .. _`edge cases`: https://github.com/python-attrs/attrs/issues/251
+
+    Args:
+        inst: Instance of a class with *attrs* attributes.
+
+        changes: Keyword changes in the new copy.
+
+    Returns:
+        A copy of inst with *changes* incorporated.
+
+    Raises:
+        attrs.exceptions.AttrsAttributeNotFoundError:
+            If *attr_name* couldn't be found on *cls*.
+
+        attrs.exceptions.NotAnAttrsClassError:
+            If *cls* is not an *attrs* class.
+
+    ..  deprecated:: 17.1.0
+        Use `attrs.evolve` instead if you can. This function will not be
+        removed du to the slightly different approach compared to
+        `attrs.evolve`, though.
+    """
+    new = copy.copy(inst)
+    attrs = fields(inst.__class__)
+    for k, v in changes.items():
+        a = getattr(attrs, k, NOTHING)
+        if a is NOTHING:
+            msg = f"{k} is not an attrs attribute on {new.__class__}."
+            raise AttrsAttributeNotFoundError(msg)
+        _OBJ_SETATTR(new, k, v)
+    return new
+
+
+def resolve_types(
+    cls, globalns=None, localns=None, attribs=None, include_extras=True
+):
+    """
+    Resolve any strings and forward annotations in type annotations.
+
+    This is only required if you need concrete types in :class:`Attribute`'s
+    *type* field. In other words, you don't need to resolve your types if you
+    only use them for static type checking.
+
+    With no arguments, names will be looked up in the module in which the class
+    was created. If this is not what you want, for example, if the name only
+    exists inside a method, you may pass *globalns* or *localns* to specify
+    other dictionaries in which to look up these names. See the docs of
+    `typing.get_type_hints` for more details.
+
+    Args:
+        cls (type): Class to resolve.
+
+        globalns (dict | None): Dictionary containing global variables.
+
+        localns (dict | None): Dictionary containing local variables.
+
+        attribs (list | None):
+            List of attribs for the given class. This is necessary when calling
+            from inside a ``field_transformer`` since *cls* is not an *attrs*
+            class yet.
+
+        include_extras (bool):
+            Resolve more accurately, if possible. Pass ``include_extras`` to
+            ``typing.get_hints``, if supported by the typing module. On
+            supported Python versions (3.9+), this resolves the types more
+            accurately.
+
+    Raises:
+        TypeError: If *cls* is not a class.
+
+        attrs.exceptions.NotAnAttrsClassError:
+            If *cls* is not an *attrs* class and you didn't pass any attribs.
+
+        NameError: If types cannot be resolved because of missing variables.
+
+    Returns:
+        *cls* so you can use this function also as a class decorator. Please
+        note that you have to apply it **after** `attrs.define`. That means the
+        decorator has to come in the line **before** `attrs.define`.
+
+    ..  versionadded:: 20.1.0
+    ..  versionadded:: 21.1.0 *attribs*
+    ..  versionadded:: 23.1.0 *include_extras*
+    """
+    # Since calling get_type_hints is expensive we cache whether we've
+    # done it already.
+    if getattr(cls, "__attrs_types_resolved__", None) != cls:
+        import typing
+
+        kwargs = {"globalns": globalns, "localns": localns}
+
+        if PY_3_9_PLUS:
+            kwargs["include_extras"] = include_extras
+
+        hints = typing.get_type_hints(cls, **kwargs)
+        for field in fields(cls) if attribs is None else attribs:
+            if field.name in hints:
+                # Since fields have been frozen we must work around it.
+                _OBJ_SETATTR(field, "type", hints[field.name])
+        # We store the class we resolved so that subclasses know they haven't
+        # been resolved.
+        cls.__attrs_types_resolved__ = cls
+
+    # Return the class so you can use it as a decorator too.
+    return cls

venv/Lib/site-packages/attr/_make.py

@@ -0,0 +1,3123 @@
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import abc
+import contextlib
+import copy
+import enum
+import inspect
+import itertools
+import linecache
+import sys
+import types
+import unicodedata
+
+from collections.abc import Callable, Mapping
+from functools import cached_property
+from typing import Any, NamedTuple, TypeVar
+
+# We need to import _compat itself in addition to the _compat members to avoid
+# having the thread-local in the globals here.
+from . import _compat, _config, setters
+from ._compat import (
+    PY_3_10_PLUS,
+    PY_3_11_PLUS,
+    PY_3_13_PLUS,
+    _AnnotationExtractor,
+    _get_annotations,
+    get_generic_base,
+)
+from .exceptions import (
+    DefaultAlreadySetError,
+    FrozenInstanceError,
+    NotAnAttrsClassError,
+    UnannotatedAttributeError,
+)
+
+
+# This is used at least twice, so cache it here.
+_OBJ_SETATTR = object.__setattr__
+_INIT_FACTORY_PAT = "__attr_factory_%s"
+_CLASSVAR_PREFIXES = (
+    "typing.ClassVar",
+    "t.ClassVar",
+    "ClassVar",
+    "typing_extensions.ClassVar",
+)
+# we don't use a double-underscore prefix because that triggers
+# name mangling when trying to create a slot for the field
+# (when slots=True)
+_HASH_CACHE_FIELD = "_attrs_cached_hash"
+
+_EMPTY_METADATA_SINGLETON = types.MappingProxyType({})
+
+# Unique object for unequivocal getattr() defaults.
+_SENTINEL = object()
+
+_DEFAULT_ON_SETATTR = setters.pipe(setters.convert, setters.validate)
+
+
+class _Nothing(enum.Enum):
+    """
+    Sentinel to indicate the lack of a value when `None` is ambiguous.
+
+    If extending attrs, you can use ``typing.Literal[NOTHING]`` to show
+    that a value may be ``NOTHING``.
+
+    .. versionchanged:: 21.1.0 ``bool(NOTHING)`` is now False.
+    .. versionchanged:: 22.2.0 ``NOTHING`` is now an ``enum.Enum`` variant.
+    """
+
+    NOTHING = enum.auto()
+
+    def __repr__(self):
+        return "NOTHING"
+
+    def __bool__(self):
+        return False
+
+
+NOTHING = _Nothing.NOTHING
+"""
+Sentinel to indicate the lack of a value when `None` is ambiguous.
+
+When using in 3rd party code, use `attrs.NothingType` for type annotations.
+"""
+
+
+class _CacheHashWrapper(int):
+    """
+    An integer subclass that pickles / copies as None
+
+    This is used for non-slots classes with ``cache_hash=True``, to avoid
+    serializing a potentially (even likely) invalid hash value. Since `None`
+    is the default value for uncalculated hashes, whenever this is copied,
+    the copy's value for the hash should automatically reset.
+
+    See GH #613 for more details.
+    """
+
+    def __reduce__(self, _none_constructor=type(None), _args=()):  # noqa: B008
+        return _none_constructor, _args
+
+
+def attrib(
+    default=NOTHING,
+    validator=None,
+    repr=True,
+    cmp=None,
+    hash=None,
+    init=True,
+    metadata=None,
+    type=None,
+    converter=None,
+    factory=None,
+    kw_only=False,
+    eq=None,
+    order=None,
+    on_setattr=None,
+    alias=None,
+):
+    """
+    Create a new field / attribute on a class.
+
+    Identical to `attrs.field`, except it's not keyword-only.
+
+    Consider using `attrs.field` in new code (``attr.ib`` will *never* go away,
+    though).
+
+    ..  warning::
+
+        Does **nothing** unless the class is also decorated with
+        `attr.s` (or similar)!
+
+
+    .. versionadded:: 15.2.0 *convert*
+    .. versionadded:: 16.3.0 *metadata*
+    .. versionchanged:: 17.1.0 *validator* can be a ``list`` now.
+    .. versionchanged:: 17.1.0
+       *hash* is `None` and therefore mirrors *eq* by default.
+    .. versionadded:: 17.3.0 *type*
+    .. deprecated:: 17.4.0 *convert*
+    .. versionadded:: 17.4.0
+       *converter* as a replacement for the deprecated *convert* to achieve
+       consistency with other noun-based arguments.
+    .. versionadded:: 18.1.0
+       ``factory=f`` is syntactic sugar for ``default=attr.Factory(f)``.
+    .. versionadded:: 18.2.0 *kw_only*
+    .. versionchanged:: 19.2.0 *convert* keyword argument removed.
+    .. versionchanged:: 19.2.0 *repr* also accepts a custom callable.
+    .. deprecated:: 19.2.0 *cmp* Removal on or after 2021-06-01.
+    .. versionadded:: 19.2.0 *eq* and *order*
+    .. versionadded:: 20.1.0 *on_setattr*
+    .. versionchanged:: 20.3.0 *kw_only* backported to Python 2
+    .. versionchanged:: 21.1.0
+       *eq*, *order*, and *cmp* also accept a custom callable
+    .. versionchanged:: 21.1.0 *cmp* undeprecated
+    .. versionadded:: 22.2.0 *alias*
+    """
+    eq, eq_key, order, order_key = _determine_attrib_eq_order(
+        cmp, eq, order, True
+    )
+
+    if hash is not None and hash is not True and hash is not False:
+        msg = "Invalid value for hash.  Must be True, False, or None."
+        raise TypeError(msg)
+
+    if factory is not None:
+        if default is not NOTHING:
+            msg = (
+                "The `default` and `factory` arguments are mutually exclusive."
+            )
+            raise ValueError(msg)
+        if not callable(factory):
+            msg = "The `factory` argument must be a callable."
+            raise ValueError(msg)
+        default = Factory(factory)
+
+    if metadata is None:
+        metadata = {}
+
+    # Apply syntactic sugar by auto-wrapping.
+    if isinstance(on_setattr, (list, tuple)):
+        on_setattr = setters.pipe(*on_setattr)
+
+    if validator and isinstance(validator, (list, tuple)):
+        validator = and_(*validator)
+
+    if converter and isinstance(converter, (list, tuple)):
+        converter = pipe(*converter)
+
+    return _CountingAttr(
+        default=default,
+        validator=validator,
+        repr=repr,
+        cmp=None,
+        hash=hash,
+        init=init,
+        converter=converter,
+        metadata=metadata,
+        type=type,
+        kw_only=kw_only,
+        eq=eq,
+        eq_key=eq_key,
+        order=order,
+        order_key=order_key,
+        on_setattr=on_setattr,
+        alias=alias,
+    )
+
+
+def _compile_and_eval(
+    script: str,
+    globs: dict[str, Any] | None,
+    locs: Mapping[str, object] | None = None,
+    filename: str = "",
+) -> None:
+    """
+    Evaluate the script with the given global (globs) and local (locs)
+    variables.
+    """
+    bytecode = compile(script, filename, "exec")
+    eval(bytecode, globs, locs)
+
+
+def _linecache_and_compile(
+    script: str,
+    filename: str,
+    globs: dict[str, Any] | None,
+    locals: Mapping[str, object] | None = None,
+) -> dict[str, Any]:
+    """
+    Cache the script with _linecache_, compile it and return the _locals_.
+    """
+
+    locs = {} if locals is None else locals
+
+    # In order of debuggers like PDB being able to step through the code,
+    # we add a fake linecache entry.
+    count = 1
+    base_filename = filename
+    while True:
+        linecache_tuple = (
+            len(script),
+            None,
+            script.splitlines(True),
+            filename,
+        )
+        old_val = linecache.cache.setdefault(filename, linecache_tuple)
+        if old_val == linecache_tuple:
+            break
+
+        filename = f"{base_filename[:-1]}-{count}>"
+        count += 1
+
+    _compile_and_eval(script, globs, locs, filename)
+
+    return locs
+
+
+def _make_attr_tuple_class(cls_name: str, attr_names: list[str]) -> type:
+    """
+    Create a tuple subclass to hold `Attribute`s for an `attrs` class.
+
+    The subclass is a bare tuple with properties for names.
+
+    class MyClassAttributes(tuple):
+        __slots__ = ()
+        x = property(itemgetter(0))
+    """
+    attr_class_name = f"{cls_name}Attributes"
+    body = {}
+    for i, attr_name in enumerate(attr_names):
+
+        def getter(self, i=i):
+            return self[i]
+
+        body[attr_name] = property(getter)
+    return type(attr_class_name, (tuple,), body)
+
+
+# Tuple class for extracted attributes from a class definition.
+# `base_attrs` is a subset of `attrs`.
+class _Attributes(NamedTuple):
+    attrs: type
+    base_attrs: list[Attribute]
+    base_attrs_map: dict[str, type]
+
+
+def _is_class_var(annot):
+    """
+    Check whether *annot* is a typing.ClassVar.
+
+    The string comparison hack is used to avoid evaluating all string
+    annotations which would put attrs-based classes at a performance
+    disadvantage compared to plain old classes.
+    """
+    annot = str(annot)
+
+    # Annotation can be quoted.
+    if annot.startswith(("'", '"')) and annot.endswith(("'", '"')):
+        annot = annot[1:-1]
+
+    return annot.startswith(_CLASSVAR_PREFIXES)
+
+
+def _has_own_attribute(cls, attrib_name):
+    """
+    Check whether *cls* defines *attrib_name* (and doesn't just inherit it).
+    """
+    return attrib_name in cls.__dict__
+
+
+def _collect_base_attrs(
+    cls, taken_attr_names
+) -> tuple[list[Attribute], dict[str, type]]:
+    """
+    Collect attr.ibs from base classes of *cls*, except *taken_attr_names*.
+    """
+    base_attrs = []
+    base_attr_map = {}  # A dictionary of base attrs to their classes.
+
+    # Traverse the MRO and collect attributes.
+    for base_cls in reversed(cls.__mro__[1:-1]):
+        for a in getattr(base_cls, "__attrs_attrs__", []):
+            if a.inherited or a.name in taken_attr_names:
+                continue
+
+            a = a.evolve(inherited=True)  # noqa: PLW2901
+            base_attrs.append(a)
+            base_attr_map[a.name] = base_cls
+
+    # For each name, only keep the freshest definition i.e. the furthest at the
+    # back.  base_attr_map is fine because it gets overwritten with every new
+    # instance.
+    filtered = []
+    seen = set()
+    for a in reversed(base_attrs):
+        if a.name in seen:
+            continue
+        filtered.insert(0, a)
+        seen.add(a.name)
+
+    return filtered, base_attr_map
+
+
+def _collect_base_attrs_broken(cls, taken_attr_names):
+    """
+    Collect attr.ibs from base classes of *cls*, except *taken_attr_names*.
+
+    N.B. *taken_attr_names* will be mutated.
+
+    Adhere to the old incorrect behavior.
+
+    Notably it collects from the front and considers inherited attributes which
+    leads to the buggy behavior reported in #428.
+    """
+    base_attrs = []
+    base_attr_map = {}  # A dictionary of base attrs to their classes.
+
+    # Traverse the MRO and collect attributes.
+    for base_cls in cls.__mro__[1:-1]:
+        for a in getattr(base_cls, "__attrs_attrs__", []):
+            if a.name in taken_attr_names:
+                continue
+
+            a = a.evolve(inherited=True)  # noqa: PLW2901
+            taken_attr_names.add(a.name)
+            base_attrs.append(a)
+            base_attr_map[a.name] = base_cls
+
+    return base_attrs, base_attr_map
+
+
+def _transform_attrs(
+    cls, these, auto_attribs, kw_only, collect_by_mro, field_transformer
+) -> _Attributes:
+    """
+    Transform all `_CountingAttr`s on a class into `Attribute`s.
+
+    If *these* is passed, use that and don't look for them on the class.
+
+    If *collect_by_mro* is True, collect them in the correct MRO order,
+    otherwise use the old -- incorrect -- order.  See #428.
+
+    Return an `_Attributes`.
+    """
+    cd = cls.__dict__
+    anns = _get_annotations(cls)
+
+    if these is not None:
+        ca_list = list(these.items())
+    elif auto_attribs is True:
+        ca_names = {
+            name
+            for name, attr in cd.items()
+            if attr.__class__ is _CountingAttr
+        }
+        ca_list = []
+        annot_names = set()
+        for attr_name, type in anns.items():
+            if _is_class_var(type):
+                continue
+            annot_names.add(attr_name)
+            a = cd.get(attr_name, NOTHING)
+
+            if a.__class__ is not _CountingAttr:
+                a = attrib(a)
+            ca_list.append((attr_name, a))
+
+        unannotated = ca_names - annot_names
+        if unannotated:
+            raise UnannotatedAttributeError(
+                "The following `attr.ib`s lack a type annotation: "
+                + ", ".join(
+                    sorted(unannotated, key=lambda n: cd.get(n).counter)
+                )
+                + "."
+            )
+    else:
+        ca_list = sorted(
+            (
+                (name, attr)
+                for name, attr in cd.items()
+                if attr.__class__ is _CountingAttr
+            ),
+            key=lambda e: e[1].counter,
+        )
+
+    fca = Attribute.from_counting_attr
+    own_attrs = [
+        fca(attr_name, ca, anns.get(attr_name)) for attr_name, ca in ca_list
+    ]
+
+    if collect_by_mro:
+        base_attrs, base_attr_map = _collect_base_attrs(
+            cls, {a.name for a in own_attrs}
+        )
+    else:
+        base_attrs, base_attr_map = _collect_base_attrs_broken(
+            cls, {a.name for a in own_attrs}
+        )
+
+    if kw_only:
+        own_attrs = [a.evolve(kw_only=True) for a in own_attrs]
+        base_attrs = [a.evolve(kw_only=True) for a in base_attrs]
+
+    attrs = base_attrs + own_attrs
+
+    if field_transformer is not None:
+        attrs = tuple(field_transformer(cls, attrs))
+
+    # Check attr order after executing the field_transformer.
+    # Mandatory vs non-mandatory attr order only matters when they are part of
+    # the __init__ signature and when they aren't kw_only (which are moved to
+    # the end and can be mandatory or non-mandatory in any order, as they will
+    # be specified as keyword args anyway). Check the order of those attrs:
+    had_default = False
+    for a in (a for a in attrs if a.init is not False and a.kw_only is False):
+        if had_default is True and a.default is NOTHING:
+            msg = f"No mandatory attributes allowed after an attribute with a default value or factory.  Attribute in question: {a!r}"
+            raise ValueError(msg)
+
+        if had_default is False and a.default is not NOTHING:
+            had_default = True
+
+    # Resolve default field alias after executing field_transformer.
+    # This allows field_transformer to differentiate between explicit vs
+    # default aliases and supply their own defaults.
+    for a in attrs:
+        if not a.alias:
+            # Evolve is very slow, so we hold our nose and do it dirty.
+            _OBJ_SETATTR.__get__(a)("alias", _default_init_alias_for(a.name))
+
+    # Create AttrsClass *after* applying the field_transformer since it may
+    # add or remove attributes!
+    attr_names = [a.name for a in attrs]
+    AttrsClass = _make_attr_tuple_class(cls.__name__, attr_names)
+
+    return _Attributes(AttrsClass(attrs), base_attrs, base_attr_map)
+
+
+def _make_cached_property_getattr(cached_properties, original_getattr, cls):
+    lines = [
+        # Wrapped to get `__class__` into closure cell for super()
+        # (It will be replaced with the newly constructed class after construction).
+        "def wrapper(_cls):",
+        "    __class__ = _cls",
+        "    def __getattr__(self, item, cached_properties=cached_properties, original_getattr=original_getattr, _cached_setattr_get=_cached_setattr_get):",
+        "         func = cached_properties.get(item)",
+        "         if func is not None:",
+        "              result = func(self)",
+        "              _setter = _cached_setattr_get(self)",
+        "              _setter(item, result)",
+        "              return result",
+    ]
+    if original_getattr is not None:
+        lines.append(
+            "         return original_getattr(self, item)",
+        )
+    else:
+        lines.extend(
+            [
+                "         try:",
+                "             return super().__getattribute__(item)",
+                "         except AttributeError:",
+                "             if not hasattr(super(), '__getattr__'):",
+                "                 raise",
+                "             return super().__getattr__(item)",
+                "         original_error = f\"'{self.__class__.__name__}' object has no attribute '{item}'\"",
+                "         raise AttributeError(original_error)",
+            ]
+        )
+
+    lines.extend(
+        [
+            "    return __getattr__",
+            "__getattr__ = wrapper(_cls)",
+        ]
+    )
+
+    unique_filename = _generate_unique_filename(cls, "getattr")
+
+    glob = {
+        "cached_properties": cached_properties,
+        "_cached_setattr_get": _OBJ_SETATTR.__get__,
+        "original_getattr": original_getattr,
+    }
+
+    return _linecache_and_compile(
+        "\n".join(lines), unique_filename, glob, locals={"_cls": cls}
+    )["__getattr__"]
+
+
+def _frozen_setattrs(self, name, value):
+    """
+    Attached to frozen classes as __setattr__.
+    """
+    if isinstance(self, BaseException) and name in (
+        "__cause__",
+        "__context__",
+        "__traceback__",
+        "__suppress_context__",
+        "__notes__",
+    ):
+        BaseException.__setattr__(self, name, value)
+        return
+
+    raise FrozenInstanceError
+
+
+def _frozen_delattrs(self, name):
+    """
+    Attached to frozen classes as __delattr__.
+    """
+    if isinstance(self, BaseException) and name in ("__notes__",):
+        BaseException.__delattr__(self, name)
+        return
+
+    raise FrozenInstanceError
+
+
+def evolve(*args, **changes):
+    """
+    Create a new instance, based on the first positional argument with
+    *changes* applied.
+
+    .. tip::
+
+       On Python 3.13 and later, you can also use `copy.replace` instead.
+
+    Args:
+
+        inst:
+            Instance of a class with *attrs* attributes. *inst* must be passed
+            as a positional argument.
+
+        changes:
+            Keyword changes in the new copy.
+
+    Returns:
+        A copy of inst with *changes* incorporated.
+
+    Raises:
+        TypeError:
+            If *attr_name* couldn't be found in the class ``__init__``.
+
+        attrs.exceptions.NotAnAttrsClassError:
+            If *cls* is not an *attrs* class.
+
+    .. versionadded:: 17.1.0
+    .. deprecated:: 23.1.0
+       It is now deprecated to pass the instance using the keyword argument
+       *inst*. It will raise a warning until at least April 2024, after which
+       it will become an error. Always pass the instance as a positional
+       argument.
+    .. versionchanged:: 24.1.0
+       *inst* can't be passed as a keyword argument anymore.
+    """
+    try:
+        (inst,) = args
+    except ValueError:
+        msg = (
+            f"evolve() takes 1 positional argument, but {len(args)} were given"
+        )
+        raise TypeError(msg) from None
+
+    cls = inst.__class__
+    attrs = fields(cls)
+    for a in attrs:
+        if not a.init:
+            continue
+        attr_name = a.name  # To deal with private attributes.
+        init_name = a.alias
+        if init_name not in changes:
+            changes[init_name] = getattr(inst, attr_name)
+
+    return cls(**changes)
+
+
+class _ClassBuilder:
+    """
+    Iteratively build *one* class.
+    """
+
+    __slots__ = (
+        "_add_method_dunders",
+        "_attr_names",
+        "_attrs",
+        "_base_attr_map",
+        "_base_names",
+        "_cache_hash",
+        "_cls",
+        "_cls_dict",
+        "_delete_attribs",
+        "_frozen",
+        "_has_custom_setattr",
+        "_has_post_init",
+        "_has_pre_init",
+        "_is_exc",
+        "_on_setattr",
+        "_pre_init_has_args",
+        "_repr_added",
+        "_script_snippets",
+        "_slots",
+        "_weakref_slot",
+        "_wrote_own_setattr",
+    )
+
+    def __init__(
+        self,
+        cls: type,
+        these,
+        slots,
+        frozen,
+        weakref_slot,
+        getstate_setstate,
+        auto_attribs,
+        kw_only,
+        cache_hash,
+        is_exc,
+        collect_by_mro,
+        on_setattr,
+        has_custom_setattr,
+        field_transformer,
+    ):
+        attrs, base_attrs, base_map = _transform_attrs(
+            cls,
+            these,
+            auto_attribs,
+            kw_only,
+            collect_by_mro,
+            field_transformer,
+        )
+
+        self._cls = cls
+        self._cls_dict = dict(cls.__dict__) if slots else {}
+        self._attrs = attrs
+        self._base_names = {a.name for a in base_attrs}
+        self._base_attr_map = base_map
+        self._attr_names = tuple(a.name for a in attrs)
+        self._slots = slots
+        self._frozen = frozen
+        self._weakref_slot = weakref_slot
+        self._cache_hash = cache_hash
+        self._has_pre_init = bool(getattr(cls, "__attrs_pre_init__", False))
+        self._pre_init_has_args = False
+        if self._has_pre_init:
+            # Check if the pre init method has more arguments than just `self`
+            # We want to pass arguments if pre init expects arguments
+            pre_init_func = cls.__attrs_pre_init__
+            pre_init_signature = inspect.signature(pre_init_func)
+            self._pre_init_has_args = len(pre_init_signature.parameters) > 1
+        self._has_post_init = bool(getattr(cls, "__attrs_post_init__", False))
+        self._delete_attribs = not bool(these)
+        self._is_exc = is_exc
+        self._on_setattr = on_setattr
+
+        self._has_custom_setattr = has_custom_setattr
+        self._wrote_own_setattr = False
+
+        self._cls_dict["__attrs_attrs__"] = self._attrs
+
+        if frozen:
+            self._cls_dict["__setattr__"] = _frozen_setattrs
+            self._cls_dict["__delattr__"] = _frozen_delattrs
+
+            self._wrote_own_setattr = True
+        elif on_setattr in (
+            _DEFAULT_ON_SETATTR,
+            setters.validate,
+            setters.convert,
+        ):
+            has_validator = has_converter = False
+            for a in attrs:
+                if a.validator is not None:
+                    has_validator = True
+                if a.converter is not None:
+                    has_converter = True
+
+                if has_validator and has_converter:
+                    break
+            if (
+                (
+                    on_setattr == _DEFAULT_ON_SETATTR
+                    and not (has_validator or has_converter)
+                )
+                or (on_setattr == setters.validate and not has_validator)
+                or (on_setattr == setters.convert and not has_converter)
+            ):
+                # If class-level on_setattr is set to convert + validate, but
+                # there's no field to convert or validate, pretend like there's
+                # no on_setattr.
+                self._on_setattr = None
+
+        if getstate_setstate:
+            (
+                self._cls_dict["__getstate__"],
+                self._cls_dict["__setstate__"],
+            ) = self._make_getstate_setstate()
+
+        # tuples of script, globs, hook
+        self._script_snippets: list[
+            tuple[str, dict, Callable[[dict, dict], Any]]
+        ] = []
+        self._repr_added = False
+
+        # We want to only do this check once; in 99.9% of cases these
+        # exist.
+        if not hasattr(self._cls, "__module__") or not hasattr(
+            self._cls, "__qualname__"
+        ):
+            self._add_method_dunders = self._add_method_dunders_safe
+        else:
+            self._add_method_dunders = self._add_method_dunders_unsafe
+
+    def __repr__(self):
+        return f"<_ClassBuilder(cls={self._cls.__name__})>"
+
+    def _eval_snippets(self) -> None:
+        """
+        Evaluate any registered snippets in one go.
+        """
+        script = "\n".join([snippet[0] for snippet in self._script_snippets])
+        globs = {}
+        for _, snippet_globs, _ in self._script_snippets:
+            globs.update(snippet_globs)
+
+        locs = _linecache_and_compile(
+            script,
+            _generate_unique_filename(self._cls, "methods"),
+            globs,
+        )
+
+        for _, _, hook in self._script_snippets:
+            hook(self._cls_dict, locs)
+
+    def build_class(self):
+        """
+        Finalize class based on the accumulated configuration.
+
+        Builder cannot be used after calling this method.
+        """
+        self._eval_snippets()
+        if self._slots is True:
+            cls = self._create_slots_class()
+        else:
+            cls = self._patch_original_class()
+            if PY_3_10_PLUS:
+                cls = abc.update_abstractmethods(cls)
+
+        # The method gets only called if it's not inherited from a base class.
+        # _has_own_attribute does NOT work properly for classmethods.
+        if (
+            getattr(cls, "__attrs_init_subclass__", None)
+            and "__attrs_init_subclass__" not in cls.__dict__
+        ):
+            cls.__attrs_init_subclass__()
+
+        return cls
+
+    def _patch_original_class(self):
+        """
+        Apply accumulated methods and return the class.
+        """
+        cls = self._cls
+        base_names = self._base_names
+
+        # Clean class of attribute definitions (`attr.ib()`s).
+        if self._delete_attribs:
+            for name in self._attr_names:
+                if (
+                    name not in base_names
+                    and getattr(cls, name, _SENTINEL) is not _SENTINEL
+                ):
+                    # An AttributeError can happen if a base class defines a
+                    # class variable and we want to set an attribute with the
+                    # same name by using only a type annotation.
+                    with contextlib.suppress(AttributeError):
+                        delattr(cls, name)
+
+        # Attach our dunder methods.
+        for name, value in self._cls_dict.items():
+            setattr(cls, name, value)
+
+        # If we've inherited an attrs __setattr__ and don't write our own,
+        # reset it to object's.
+        if not self._wrote_own_setattr and getattr(
+            cls, "__attrs_own_setattr__", False
+        ):
+            cls.__attrs_own_setattr__ = False
+
+            if not self._has_custom_setattr:
+                cls.__setattr__ = _OBJ_SETATTR
+
+        return cls
+
+    def _create_slots_class(self):
+        """
+        Build and return a new class with a `__slots__` attribute.
+        """
+        cd = {
+            k: v
+            for k, v in self._cls_dict.items()
+            if k not in (*tuple(self._attr_names), "__dict__", "__weakref__")
+        }
+
+        # If our class doesn't have its own implementation of __setattr__
+        # (either from the user or by us), check the bases, if one of them has
+        # an attrs-made __setattr__, that needs to be reset. We don't walk the
+        # MRO because we only care about our immediate base classes.
+        # XXX: This can be confused by subclassing a slotted attrs class with
+        # XXX: a non-attrs class and subclass the resulting class with an attrs
+        # XXX: class.  See `test_slotted_confused` for details.  For now that's
+        # XXX: OK with us.
+        if not self._wrote_own_setattr:
+            cd["__attrs_own_setattr__"] = False
+
+            if not self._has_custom_setattr:
+                for base_cls in self._cls.__bases__:
+                    if base_cls.__dict__.get("__attrs_own_setattr__", False):
+                        cd["__setattr__"] = _OBJ_SETATTR
+                        break
+
+        # Traverse the MRO to collect existing slots
+        # and check for an existing __weakref__.
+        existing_slots = {}
+        weakref_inherited = False
+        for base_cls in self._cls.__mro__[1:-1]:
+            if base_cls.__dict__.get("__weakref__", None) is not None:
+                weakref_inherited = True
+            existing_slots.update(
+                {
+                    name: getattr(base_cls, name)
+                    for name in getattr(base_cls, "__slots__", [])
+                }
+            )
+
+        base_names = set(self._base_names)
+
+        names = self._attr_names
+        if (
+            self._weakref_slot
+            and "__weakref__" not in getattr(self._cls, "__slots__", ())
+            and "__weakref__" not in names
+            and not weakref_inherited
+        ):
+            names += ("__weakref__",)
+
+        cached_properties = {
+            name: cached_prop.func
+            for name, cached_prop in cd.items()
+            if isinstance(cached_prop, cached_property)
+        }
+
+        # Collect methods with a `__class__` reference that are shadowed in the new class.
+        # To know to update them.
+        additional_closure_functions_to_update = []
+        if cached_properties:
+            class_annotations = _get_annotations(self._cls)
+            for name, func in cached_properties.items():
+                # Add cached properties to names for slotting.
+                names += (name,)
+                # Clear out function from class to avoid clashing.
+                del cd[name]
+                additional_closure_functions_to_update.append(func)
+                annotation = inspect.signature(func).return_annotation
+                if annotation is not inspect.Parameter.empty:
+                    class_annotations[name] = annotation
+
+            original_getattr = cd.get("__getattr__")
+            if original_getattr is not None:
+                additional_closure_functions_to_update.append(original_getattr)
+
+            cd["__getattr__"] = _make_cached_property_getattr(
+                cached_properties, original_getattr, self._cls
+            )
+
+        # We only add the names of attributes that aren't inherited.
+        # Setting __slots__ to inherited attributes wastes memory.
+        slot_names = [name for name in names if name not in base_names]
+
+        # There are slots for attributes from current class
+        # that are defined in parent classes.
+        # As their descriptors may be overridden by a child class,
+        # we collect them here and update the class dict
+        reused_slots = {
+            slot: slot_descriptor
+            for slot, slot_descriptor in existing_slots.items()
+            if slot in slot_names
+        }
+        slot_names = [name for name in slot_names if name not in reused_slots]
+        cd.update(reused_slots)
+        if self._cache_hash:
+            slot_names.append(_HASH_CACHE_FIELD)
+
+        cd["__slots__"] = tuple(slot_names)
+
+        cd["__qualname__"] = self._cls.__qualname__
+
+        # Create new class based on old class and our methods.
+        cls = type(self._cls)(self._cls.__name__, self._cls.__bases__, cd)
+
+        # The following is a fix for
+        # <https://github.com/python-attrs/attrs/issues/102>.
+        # If a method mentions `__class__` or uses the no-arg super(), the
+        # compiler will bake a reference to the class in the method itself
+        # as `method.__closure__`.  Since we replace the class with a
+        # clone, we rewrite these references so it keeps working.
+        for item in itertools.chain(
+            cls.__dict__.values(), additional_closure_functions_to_update
+        ):
+            if isinstance(item, (classmethod, staticmethod)):
+                # Class- and staticmethods hide their functions inside.
+                # These might need to be rewritten as well.
+                closure_cells = getattr(item.__func__, "__closure__", None)
+            elif isinstance(item, property):
+                # Workaround for property `super()` shortcut (PY3-only).
+                # There is no universal way for other descriptors.
+                closure_cells = getattr(item.fget, "__closure__", None)
+            else:
+                closure_cells = getattr(item, "__closure__", None)
+
+            if not closure_cells:  # Catch None or the empty list.
+                continue
+            for cell in closure_cells:
+                try:
+                    match = cell.cell_contents is self._cls
+                except ValueError:  # noqa: PERF203
+                    # ValueError: Cell is empty
+                    pass
+                else:
+                    if match:
+                        cell.cell_contents = cls
+        return cls
+
+    def add_repr(self, ns):
+        script, globs = _make_repr_script(self._attrs, ns)
+
+        def _attach_repr(cls_dict, globs):
+            cls_dict["__repr__"] = self._add_method_dunders(globs["__repr__"])
+
+        self._script_snippets.append((script, globs, _attach_repr))
+        self._repr_added = True
+        return self
+
+    def add_str(self):
+        if not self._repr_added:
+            msg = "__str__ can only be generated if a __repr__ exists."
+            raise ValueError(msg)
+
+        def __str__(self):
+            return self.__repr__()
+
+        self._cls_dict["__str__"] = self._add_method_dunders(__str__)
+        return self
+
+    def _make_getstate_setstate(self):
+        """
+        Create custom __setstate__ and __getstate__ methods.
+        """
+        # __weakref__ is not writable.
+        state_attr_names = tuple(
+            an for an in self._attr_names if an != "__weakref__"
+        )
+
+        def slots_getstate(self):
+            """
+            Automatically created by attrs.
+            """
+            return {name: getattr(self, name) for name in state_attr_names}
+
+        hash_caching_enabled = self._cache_hash
+
+        def slots_setstate(self, state):
+            """
+            Automatically created by attrs.
+            """
+            __bound_setattr = _OBJ_SETATTR.__get__(self)
+            if isinstance(state, tuple):
+                # Backward compatibility with attrs instances pickled with
+                # attrs versions before v22.2.0 which stored tuples.
+                for name, value in zip(state_attr_names, state):
+                    __bound_setattr(name, value)
+            else:
+                for name in state_attr_names:
+                    if name in state:
+                        __bound_setattr(name, state[name])
+
+            # The hash code cache is not included when the object is
+            # serialized, but it still needs to be initialized to None to
+            # indicate that the first call to __hash__ should be a cache
+            # miss.
+            if hash_caching_enabled:
+                __bound_setattr(_HASH_CACHE_FIELD, None)
+
+        return slots_getstate, slots_setstate
+
+    def make_unhashable(self):
+        self._cls_dict["__hash__"] = None
+        return self
+
+    def add_hash(self):
+        script, globs = _make_hash_script(
+            self._cls,
+            self._attrs,
+            frozen=self._frozen,
+            cache_hash=self._cache_hash,
+        )
+
+        def attach_hash(cls_dict: dict, locs: dict) -> None:
+            cls_dict["__hash__"] = self._add_method_dunders(locs["__hash__"])
+
+        self._script_snippets.append((script, globs, attach_hash))
+
+        return self
+
+    def add_init(self):
+        script, globs, annotations = _make_init_script(
+            self._cls,
+            self._attrs,
+            self._has_pre_init,
+            self._pre_init_has_args,
+            self._has_post_init,
+            self._frozen,
+            self._slots,
+            self._cache_hash,
+            self._base_attr_map,
+            self._is_exc,
+            self._on_setattr,
+            attrs_init=False,
+        )
+
+        def _attach_init(cls_dict, globs):
+            init = globs["__init__"]
+            init.__annotations__ = annotations
+            cls_dict["__init__"] = self._add_method_dunders(init)
+
+        self._script_snippets.append((script, globs, _attach_init))
+
+        return self
+
+    def add_replace(self):
+        self._cls_dict["__replace__"] = self._add_method_dunders(
+            lambda self, **changes: evolve(self, **changes)
+        )
+        return self
+
+    def add_match_args(self):
+        self._cls_dict["__match_args__"] = tuple(
+            field.name
+            for field in self._attrs
+            if field.init and not field.kw_only
+        )
+
+    def add_attrs_init(self):
+        script, globs, annotations = _make_init_script(
+            self._cls,
+            self._attrs,
+            self._has_pre_init,
+            self._pre_init_has_args,
+            self._has_post_init,
+            self._frozen,
+            self._slots,
+            self._cache_hash,
+            self._base_attr_map,
+            self._is_exc,
+            self._on_setattr,
+            attrs_init=True,
+        )
+
+        def _attach_attrs_init(cls_dict, globs):
+            init = globs["__attrs_init__"]
+            init.__annotations__ = annotations
+            cls_dict["__attrs_init__"] = self._add_method_dunders(init)
+
+        self._script_snippets.append((script, globs, _attach_attrs_init))
+
+        return self
+
+    def add_eq(self):
+        cd = self._cls_dict
+
+        script, globs = _make_eq_script(self._attrs)
+
+        def _attach_eq(cls_dict, globs):
+            cls_dict["__eq__"] = self._add_method_dunders(globs["__eq__"])
+
+        self._script_snippets.append((script, globs, _attach_eq))
+
+        cd["__ne__"] = __ne__
+
+        return self
+
+    def add_order(self):
+        cd = self._cls_dict
+
+        cd["__lt__"], cd["__le__"], cd["__gt__"], cd["__ge__"] = (
+            self._add_method_dunders(meth)
+            for meth in _make_order(self._cls, self._attrs)
+        )
+
+        return self
+
+    def add_setattr(self):
+        sa_attrs = {}
+        for a in self._attrs:
+            on_setattr = a.on_setattr or self._on_setattr
+            if on_setattr and on_setattr is not setters.NO_OP:
+                sa_attrs[a.name] = a, on_setattr
+
+        if not sa_attrs:
+            return self
+
+        if self._has_custom_setattr:
+            # We need to write a __setattr__ but there already is one!
+            msg = "Can't combine custom __setattr__ with on_setattr hooks."
+            raise ValueError(msg)
+
+        # docstring comes from _add_method_dunders
+        def __setattr__(self, name, val):
+            try:
+                a, hook = sa_attrs[name]
+            except KeyError:
+                nval = val
+            else:
+                nval = hook(self, a, val)
+
+            _OBJ_SETATTR(self, name, nval)
+
+        self._cls_dict["__attrs_own_setattr__"] = True
+        self._cls_dict["__setattr__"] = self._add_method_dunders(__setattr__)
+        self._wrote_own_setattr = True
+
+        return self
+
+    def _add_method_dunders_unsafe(self, method: Callable) -> Callable:
+        """
+        Add __module__ and __qualname__ to a *method*.
+        """
+        method.__module__ = self._cls.__module__
+
+        method.__qualname__ = f"{self._cls.__qualname__}.{method.__name__}"
+
+        method.__doc__ = (
+            f"Method generated by attrs for class {self._cls.__qualname__}."
+        )
+
+        return method
+
+    def _add_method_dunders_safe(self, method: Callable) -> Callable:
+        """
+        Add __module__ and __qualname__ to a *method* if possible.
+        """
+        with contextlib.suppress(AttributeError):
+            method.__module__ = self._cls.__module__
+
+        with contextlib.suppress(AttributeError):
+            method.__qualname__ = f"{self._cls.__qualname__}.{method.__name__}"
+
+        with contextlib.suppress(AttributeError):
+            method.__doc__ = f"Method generated by attrs for class {self._cls.__qualname__}."
+
+        return method
+
+
+def _determine_attrs_eq_order(cmp, eq, order, default_eq):
+    """
+    Validate the combination of *cmp*, *eq*, and *order*. Derive the effective
+    values of eq and order.  If *eq* is None, set it to *default_eq*.
+    """
+    if cmp is not None and any((eq is not None, order is not None)):
+        msg = "Don't mix `cmp` with `eq' and `order`."
+        raise ValueError(msg)
+
+    # cmp takes precedence due to bw-compatibility.
+    if cmp is not None:
+        return cmp, cmp
+
+    # If left None, equality is set to the specified default and ordering
+    # mirrors equality.
+    if eq is None:
+        eq = default_eq
+
+    if order is None:
+        order = eq
+
+    if eq is False and order is True:
+        msg = "`order` can only be True if `eq` is True too."
+        raise ValueError(msg)
+
+    return eq, order
+
+
+def _determine_attrib_eq_order(cmp, eq, order, default_eq):
+    """
+    Validate the combination of *cmp*, *eq*, and *order*. Derive the effective
+    values of eq and order.  If *eq* is None, set it to *default_eq*.
+    """
+    if cmp is not None and any((eq is not None, order is not None)):
+        msg = "Don't mix `cmp` with `eq' and `order`."
+        raise ValueError(msg)
+
+    def decide_callable_or_boolean(value):
+        """
+        Decide whether a key function is used.
+        """
+        if callable(value):
+            value, key = True, value
+        else:
+            key = None
+        return value, key
+
+    # cmp takes precedence due to bw-compatibility.
+    if cmp is not None:
+        cmp, cmp_key = decide_callable_or_boolean(cmp)
+        return cmp, cmp_key, cmp, cmp_key
+
+    # If left None, equality is set to the specified default and ordering
+    # mirrors equality.
+    if eq is None:
+        eq, eq_key = default_eq, None
+    else:
+        eq, eq_key = decide_callable_or_boolean(eq)
+
+    if order is None:
+        order, order_key = eq, eq_key
+    else:
+        order, order_key = decide_callable_or_boolean(order)
+
+    if eq is False and order is True:
+        msg = "`order` can only be True if `eq` is True too."
+        raise ValueError(msg)
+
+    return eq, eq_key, order, order_key
+
+
+def _determine_whether_to_implement(
+    cls, flag, auto_detect, dunders, default=True
+):
+    """
+    Check whether we should implement a set of methods for *cls*.
+
+    *flag* is the argument passed into @attr.s like 'init', *auto_detect* the
+    same as passed into @attr.s and *dunders* is a tuple of attribute names
+    whose presence signal that the user has implemented it themselves.
+
+    Return *default* if no reason for either for or against is found.
+    """
+    if flag is True or flag is False:
+        return flag
+
+    if flag is None and auto_detect is False:
+        return default
+
+    # Logically, flag is None and auto_detect is True here.
+    for dunder in dunders:
+        if _has_own_attribute(cls, dunder):
+            return False
+
+    return default
+
+
+def attrs(
+    maybe_cls=None,
+    these=None,
+    repr_ns=None,
+    repr=None,
+    cmp=None,
+    hash=None,
+    init=None,
+    slots=False,
+    frozen=False,
+    weakref_slot=True,
+    str=False,
+    auto_attribs=False,
+    kw_only=False,
+    cache_hash=False,
+    auto_exc=False,
+    eq=None,
+    order=None,
+    auto_detect=False,
+    collect_by_mro=False,
+    getstate_setstate=None,
+    on_setattr=None,
+    field_transformer=None,
+    match_args=True,
+    unsafe_hash=None,
+):
+    r"""
+    A class decorator that adds :term:`dunder methods` according to the
+    specified attributes using `attr.ib` or the *these* argument.
+
+    Consider using `attrs.define` / `attrs.frozen` in new code (``attr.s`` will
+    *never* go away, though).
+
+    Args:
+        repr_ns (str):
+            When using nested classes, there was no way in Python 2 to
+            automatically detect that.  This argument allows to set a custom
+            name for a more meaningful ``repr`` output.  This argument is
+            pointless in Python 3 and is therefore deprecated.
+
+    .. caution::
+        Refer to `attrs.define` for the rest of the parameters, but note that they
+        can have different defaults.
+
+        Notably, leaving *on_setattr* as `None` will **not** add any hooks.
+
+    .. versionadded:: 16.0.0 *slots*
+    .. versionadded:: 16.1.0 *frozen*
+    .. versionadded:: 16.3.0 *str*
+    .. versionadded:: 16.3.0 Support for ``__attrs_post_init__``.
+    .. versionchanged:: 17.1.0
+       *hash* supports `None` as value which is also the default now.
+    .. versionadded:: 17.3.0 *auto_attribs*
+    .. versionchanged:: 18.1.0
+       If *these* is passed, no attributes are deleted from the class body.
+    .. versionchanged:: 18.1.0 If *these* is ordered, the order is retained.
+    .. versionadded:: 18.2.0 *weakref_slot*
+    .. deprecated:: 18.2.0
+       ``__lt__``, ``__le__``, ``__gt__``, and ``__ge__`` now raise a
+       `DeprecationWarning` if the classes compared are subclasses of
+       each other. ``__eq`` and ``__ne__`` never tried to compared subclasses
+       to each other.
+    .. versionchanged:: 19.2.0
+       ``__lt__``, ``__le__``, ``__gt__``, and ``__ge__`` now do not consider
+       subclasses comparable anymore.
+    .. versionadded:: 18.2.0 *kw_only*
+    .. versionadded:: 18.2.0 *cache_hash*
+    .. versionadded:: 19.1.0 *auto_exc*
+    .. deprecated:: 19.2.0 *cmp* Removal on or after 2021-06-01.
+    .. versionadded:: 19.2.0 *eq* and *order*
+    .. versionadded:: 20.1.0 *auto_detect*
+    .. versionadded:: 20.1.0 *collect_by_mro*
+    .. versionadded:: 20.1.0 *getstate_setstate*
+    .. versionadded:: 20.1.0 *on_setattr*
+    .. versionadded:: 20.3.0 *field_transformer*
+    .. versionchanged:: 21.1.0
+       ``init=False`` injects ``__attrs_init__``
+    .. versionchanged:: 21.1.0 Support for ``__attrs_pre_init__``
+    .. versionchanged:: 21.1.0 *cmp* undeprecated
+    .. versionadded:: 21.3.0 *match_args*
+    .. versionadded:: 22.2.0
+       *unsafe_hash* as an alias for *hash* (for :pep:`681` compliance).
+    .. deprecated:: 24.1.0 *repr_ns*
+    .. versionchanged:: 24.1.0
+       Instances are not compared as tuples of attributes anymore, but using a
+       big ``and`` condition. This is faster and has more correct behavior for
+       uncomparable values like `math.nan`.
+    .. versionadded:: 24.1.0
+       If a class has an *inherited* classmethod called
+       ``__attrs_init_subclass__``, it is executed after the class is created.
+    .. deprecated:: 24.1.0 *hash* is deprecated in favor of *unsafe_hash*.
+    """
+    if repr_ns is not None:
+        import warnings
+
+        warnings.warn(
+            DeprecationWarning(
+                "The `repr_ns` argument is deprecated and will be removed in or after August 2025."
+            ),
+            stacklevel=2,
+        )
+
+    eq_, order_ = _determine_attrs_eq_order(cmp, eq, order, None)
+
+    #  unsafe_hash takes precedence due to PEP 681.
+    if unsafe_hash is not None:
+        hash = unsafe_hash
+
+    if isinstance(on_setattr, (list, tuple)):
+        on_setattr = setters.pipe(*on_setattr)
+
+    def wrap(cls):
+        is_frozen = frozen or _has_frozen_base_class(cls)
+        is_exc = auto_exc is True and issubclass(cls, BaseException)
+        has_own_setattr = auto_detect and _has_own_attribute(
+            cls, "__setattr__"
+        )
+
+        if has_own_setattr and is_frozen:
+            msg = "Can't freeze a class with a custom __setattr__."
+            raise ValueError(msg)
+
+        builder = _ClassBuilder(
+            cls,
+            these,
+            slots,
+            is_frozen,
+            weakref_slot,
+            _determine_whether_to_implement(
+                cls,
+                getstate_setstate,
+                auto_detect,
+                ("__getstate__", "__setstate__"),
+                default=slots,
+            ),
+            auto_attribs,
+            kw_only,
+            cache_hash,
+            is_exc,
+            collect_by_mro,
+            on_setattr,
+            has_own_setattr,
+            field_transformer,
+        )
+
+        if _determine_whether_to_implement(
+            cls, repr, auto_detect, ("__repr__",)
+        ):
+            builder.add_repr(repr_ns)
+
+        if str is True:
+            builder.add_str()
+
+        eq = _determine_whether_to_implement(
+            cls, eq_, auto_detect, ("__eq__", "__ne__")
+        )
+        if not is_exc and eq is True:
+            builder.add_eq()
+        if not is_exc and _determine_whether_to_implement(
+            cls, order_, auto_detect, ("__lt__", "__le__", "__gt__", "__ge__")
+        ):
+            builder.add_order()
+
+        if not frozen:
+            builder.add_setattr()
+
+        nonlocal hash
+        if (
+            hash is None
+            and auto_detect is True
+            and _has_own_attribute(cls, "__hash__")
+        ):
+            hash = False
+
+        if hash is not True and hash is not False and hash is not None:
+            # Can't use `hash in` because 1 == True for example.
+            msg = "Invalid value for hash.  Must be True, False, or None."
+            raise TypeError(msg)
+
+        if hash is False or (hash is None and eq is False) or is_exc:
+            # Don't do anything. Should fall back to __object__'s __hash__
+            # which is by id.
+            if cache_hash:
+                msg = "Invalid value for cache_hash.  To use hash caching, hashing must be either explicitly or implicitly enabled."
+                raise TypeError(msg)
+        elif hash is True or (
+            hash is None and eq is True and is_frozen is True
+        ):
+            # Build a __hash__ if told so, or if it's safe.
+            builder.add_hash()
+        else:
+            # Raise TypeError on attempts to hash.
+            if cache_hash:
+                msg = "Invalid value for cache_hash.  To use hash caching, hashing must be either explicitly or implicitly enabled."
+                raise TypeError(msg)
+            builder.make_unhashable()
+
+        if _determine_whether_to_implement(
+            cls, init, auto_detect, ("__init__",)
+        ):
+            builder.add_init()
+        else:
+            builder.add_attrs_init()
+            if cache_hash:
+                msg = "Invalid value for cache_hash.  To use hash caching, init must be True."
+                raise TypeError(msg)
+
+        if PY_3_13_PLUS and not _has_own_attribute(cls, "__replace__"):
+            builder.add_replace()
+
+        if (
+            PY_3_10_PLUS
+            and match_args
+            and not _has_own_attribute(cls, "__match_args__")
+        ):
+            builder.add_match_args()
+
+        return builder.build_class()
+
+    # maybe_cls's type depends on the usage of the decorator.  It's a class
+    # if it's used as `@attrs` but `None` if used as `@attrs()`.
+    if maybe_cls is None:
+        return wrap
+
+    return wrap(maybe_cls)
+
+
+_attrs = attrs
+"""
+Internal alias so we can use it in functions that take an argument called
+*attrs*.
+"""
+
+
+def _has_frozen_base_class(cls):
+    """
+    Check whether *cls* has a frozen ancestor by looking at its
+    __setattr__.
+    """
+    return cls.__setattr__ is _frozen_setattrs
+
+
+def _generate_unique_filename(cls: type, func_name: str) -> str:
+    """
+    Create a "filename" suitable for a function being generated.
+    """
+    return (
+        f"<attrs generated {func_name} {cls.__module__}."
+        f"{getattr(cls, '__qualname__', cls.__name__)}>"
+    )
+
+
+def _make_hash_script(
+    cls: type, attrs: list[Attribute], frozen: bool, cache_hash: bool
+) -> tuple[str, dict]:
+    attrs = tuple(
+        a for a in attrs if a.hash is True or (a.hash is None and a.eq is True)
+    )
+
+    tab = "        "
+
+    type_hash = hash(_generate_unique_filename(cls, "hash"))
+    # If eq is custom generated, we need to include the functions in globs
+    globs = {}
+
+    hash_def = "def __hash__(self"
+    hash_func = "hash(("
+    closing_braces = "))"
+    if not cache_hash:
+        hash_def += "):"
+    else:
+        hash_def += ", *"
+
+        hash_def += ", _cache_wrapper=__import__('attr._make')._make._CacheHashWrapper):"
+        hash_func = "_cache_wrapper(" + hash_func
+        closing_braces += ")"
+
+    method_lines = [hash_def]
+
+    def append_hash_computation_lines(prefix, indent):
+        """
+        Generate the code for actually computing the hash code.
+        Below this will either be returned directly or used to compute
+        a value which is then cached, depending on the value of cache_hash
+        """
+
+        method_lines.extend(
+            [
+                indent + prefix + hash_func,
+                indent + f"        {type_hash},",
+            ]
+        )
+
+        for a in attrs:
+            if a.eq_key:
+                cmp_name = f"_{a.name}_key"
+                globs[cmp_name] = a.eq_key
+                method_lines.append(
+                    indent + f"        {cmp_name}(self.{a.name}),"
+                )
+            else:
+                method_lines.append(indent + f"        self.{a.name},")
+
+        method_lines.append(indent + "    " + closing_braces)
+
+    if cache_hash:
+        method_lines.append(tab + f"if self.{_HASH_CACHE_FIELD} is None:")
+        if frozen:
+            append_hash_computation_lines(
+                f"object.__setattr__(self, '{_HASH_CACHE_FIELD}', ", tab * 2
+            )
+            method_lines.append(tab * 2 + ")")  # close __setattr__
+        else:
+            append_hash_computation_lines(
+                f"self.{_HASH_CACHE_FIELD} = ", tab * 2
+            )
+        method_lines.append(tab + f"return self.{_HASH_CACHE_FIELD}")
+    else:
+        append_hash_computation_lines("return ", tab)
+
+    script = "\n".join(method_lines)
+    return script, globs
+
+
+def _add_hash(cls: type, attrs: list[Attribute]):
+    """
+    Add a hash method to *cls*.
+    """
+    script, globs = _make_hash_script(
+        cls, attrs, frozen=False, cache_hash=False
+    )
+    _compile_and_eval(
+        script, globs, filename=_generate_unique_filename(cls, "__hash__")
+    )
+    cls.__hash__ = globs["__hash__"]
+    return cls
+
+
+def __ne__(self, other):
+    """
+    Check equality and either forward a NotImplemented or
+    return the result negated.
+    """
+    result = self.__eq__(other)
+    if result is NotImplemented:
+        return NotImplemented
+
+    return not result
+
+
+def _make_eq_script(attrs: list) -> tuple[str, dict]:
+    """
+    Create __eq__ method for *cls* with *attrs*.
+    """
+    attrs = [a for a in attrs if a.eq]
+
+    lines = [
+        "def __eq__(self, other):",
+        "    if other.__class__ is not self.__class__:",
+        "        return NotImplemented",
+    ]
+
+    globs = {}
+    if attrs:
+        lines.append("    return  (")
+        for a in attrs:
+            if a.eq_key:
+                cmp_name = f"_{a.name}_key"
+                # Add the key function to the global namespace
+                # of the evaluated function.
+                globs[cmp_name] = a.eq_key
+                lines.append(
+                    f"        {cmp_name}(self.{a.name}) == {cmp_name}(other.{a.name})"
+                )
+            else:
+                lines.append(f"        self.{a.name} == other.{a.name}")
+            if a is not attrs[-1]:
+                lines[-1] = f"{lines[-1]} and"
+        lines.append("    )")
+    else:
+        lines.append("    return True")
+
+    script = "\n".join(lines)
+
+    return script, globs
+
+
+def _make_order(cls, attrs):
+    """
+    Create ordering methods for *cls* with *attrs*.
+    """
+    attrs = [a for a in attrs if a.order]
+
+    def attrs_to_tuple(obj):
+        """
+        Save us some typing.
+        """
+        return tuple(
+            key(value) if key else value
+            for value, key in (
+                (getattr(obj, a.name), a.order_key) for a in attrs
+            )
+        )
+
+    def __lt__(self, other):
+        """
+        Automatically created by attrs.
+        """
+        if other.__class__ is self.__class__:
+            return attrs_to_tuple(self) < attrs_to_tuple(other)
+
+        return NotImplemented
+
+    def __le__(self, other):
+        """
+        Automatically created by attrs.
+        """
+        if other.__class__ is self.__class__:
+            return attrs_to_tuple(self) <= attrs_to_tuple(other)
+
+        return NotImplemented
+
+    def __gt__(self, other):
+        """
+        Automatically created by attrs.
+        """
+        if other.__class__ is self.__class__:
+            return attrs_to_tuple(self) > attrs_to_tuple(other)
+
+        return NotImplemented
+
+    def __ge__(self, other):
+        """
+        Automatically created by attrs.
+        """
+        if other.__class__ is self.__class__:
+            return attrs_to_tuple(self) >= attrs_to_tuple(other)
+
+        return NotImplemented
+
+    return __lt__, __le__, __gt__, __ge__
+
+
+def _add_eq(cls, attrs=None):
+    """
+    Add equality methods to *cls* with *attrs*.
+    """
+    if attrs is None:
+        attrs = cls.__attrs_attrs__
+
+    script, globs = _make_eq_script(attrs)
+    _compile_and_eval(
+        script, globs, filename=_generate_unique_filename(cls, "__eq__")
+    )
+    cls.__eq__ = globs["__eq__"]
+    cls.__ne__ = __ne__
+
+    return cls
+
+
+def _make_repr_script(attrs, ns) -> tuple[str, dict]:
+    """
+    Create the source and globs for a __repr__ and return it.
+    """
+    # Figure out which attributes to include, and which function to use to
+    # format them. The a.repr value can be either bool or a custom
+    # callable.
+    attr_names_with_reprs = tuple(
+        (a.name, (repr if a.repr is True else a.repr), a.init)
+        for a in attrs
+        if a.repr is not False
+    )
+    globs = {
+        name + "_repr": r for name, r, _ in attr_names_with_reprs if r != repr
+    }
+    globs["_compat"] = _compat
+    globs["AttributeError"] = AttributeError
+    globs["NOTHING"] = NOTHING
+    attribute_fragments = []
+    for name, r, i in attr_names_with_reprs:
+        accessor = (
+            "self." + name if i else 'getattr(self, "' + name + '", NOTHING)'
+        )
+        fragment = (
+            "%s={%s!r}" % (name, accessor)
+            if r == repr
+            else "%s={%s_repr(%s)}" % (name, name, accessor)
+        )
+        attribute_fragments.append(fragment)
+    repr_fragment = ", ".join(attribute_fragments)
+
+    if ns is None:
+        cls_name_fragment = '{self.__class__.__qualname__.rsplit(">.", 1)[-1]}'
+    else:
+        cls_name_fragment = ns + ".{self.__class__.__name__}"
+
+    lines = [
+        "def __repr__(self):",
+        "  try:",
+        "    already_repring = _compat.repr_context.already_repring",
+        "  except AttributeError:",
+        "    already_repring = {id(self),}",
+        "    _compat.repr_context.already_repring = already_repring",
+        "  else:",
+        "    if id(self) in already_repring:",
+        "      return '...'",
+        "    else:",
+        "      already_repring.add(id(self))",
+        "  try:",
+        f"    return f'{cls_name_fragment}({repr_fragment})'",
+        "  finally:",
+        "    already_repring.remove(id(self))",
+    ]
+
+    return "\n".join(lines), globs
+
+
+def _add_repr(cls, ns=None, attrs=None):
+    """
+    Add a repr method to *cls*.
+    """
+    if attrs is None:
+        attrs = cls.__attrs_attrs__
+
+    script, globs = _make_repr_script(attrs, ns)
+    _compile_and_eval(
+        script, globs, filename=_generate_unique_filename(cls, "__repr__")
+    )
+    cls.__repr__ = globs["__repr__"]
+    return cls
+
+
+def fields(cls):
+    """
+    Return the tuple of *attrs* attributes for a class.
+
+    The tuple also allows accessing the fields by their names (see below for
+    examples).
+
+    Args:
+        cls (type): Class to introspect.
+
+    Raises:
+        TypeError: If *cls* is not a class.
+
+        attrs.exceptions.NotAnAttrsClassError:
+            If *cls* is not an *attrs* class.
+
+    Returns:
+        tuple (with name accessors) of `attrs.Attribute`
+
+    .. versionchanged:: 16.2.0 Returned tuple allows accessing the fields
+       by name.
+    .. versionchanged:: 23.1.0 Add support for generic classes.
+    """
+    generic_base = get_generic_base(cls)
+
+    if generic_base is None and not isinstance(cls, type):
+        msg = "Passed object must be a class."
+        raise TypeError(msg)
+
+    attrs = getattr(cls, "__attrs_attrs__", None)
+
+    if attrs is None:
+        if generic_base is not None:
+            attrs = getattr(generic_base, "__attrs_attrs__", None)
+            if attrs is not None:
+                # Even though this is global state, stick it on here to speed
+                # it up. We rely on `cls` being cached for this to be
+                # efficient.
+                cls.__attrs_attrs__ = attrs
+                return attrs
+        msg = f"{cls!r} is not an attrs-decorated class."
+        raise NotAnAttrsClassError(msg)
+
+    return attrs
+
+
+def fields_dict(cls):
+    """
+    Return an ordered dictionary of *attrs* attributes for a class, whose keys
+    are the attribute names.
+
+    Args:
+        cls (type): Class to introspect.
+
+    Raises:
+        TypeError: If *cls* is not a class.
+
+        attrs.exceptions.NotAnAttrsClassError:
+            If *cls* is not an *attrs* class.
+
+    Returns:
+        dict[str, attrs.Attribute]: Dict of attribute name to definition
+
+    .. versionadded:: 18.1.0
+    """
+    if not isinstance(cls, type):
+        msg = "Passed object must be a class."
+        raise TypeError(msg)
+    attrs = getattr(cls, "__attrs_attrs__", None)
+    if attrs is None:
+        msg = f"{cls!r} is not an attrs-decorated class."
+        raise NotAnAttrsClassError(msg)
+    return {a.name: a for a in attrs}
+
+
+def validate(inst):
+    """
+    Validate all attributes on *inst* that have a validator.
+
+    Leaves all exceptions through.
+
+    Args:
+        inst: Instance of a class with *attrs* attributes.
+    """
+    if _config._run_validators is False:
+        return
+
+    for a in fields(inst.__class__):
+        v = a.validator
+        if v is not None:
+            v(inst, a, getattr(inst, a.name))
+
+
+def _is_slot_attr(a_name, base_attr_map):
+    """
+    Check if the attribute name comes from a slot class.
+    """
+    cls = base_attr_map.get(a_name)
+    return cls and "__slots__" in cls.__dict__
+
+
+def _make_init_script(
+    cls,
+    attrs,
+    pre_init,
+    pre_init_has_args,
+    post_init,
+    frozen,
+    slots,
+    cache_hash,
+    base_attr_map,
+    is_exc,
+    cls_on_setattr,
+    attrs_init,
+) -> tuple[str, dict, dict]:
+    has_cls_on_setattr = (
+        cls_on_setattr is not None and cls_on_setattr is not setters.NO_OP
+    )
+
+    if frozen and has_cls_on_setattr:
+        msg = "Frozen classes can't use on_setattr."
+        raise ValueError(msg)
+
+    needs_cached_setattr = cache_hash or frozen
+    filtered_attrs = []
+    attr_dict = {}
+    for a in attrs:
+        if not a.init and a.default is NOTHING:
+            continue
+
+        filtered_attrs.append(a)
+        attr_dict[a.name] = a
+
+        if a.on_setattr is not None:
+            if frozen is True:
+                msg = "Frozen classes can't use on_setattr."
+                raise ValueError(msg)
+
+            needs_cached_setattr = True
+        elif has_cls_on_setattr and a.on_setattr is not setters.NO_OP:
+            needs_cached_setattr = True
+
+    script, globs, annotations = _attrs_to_init_script(
+        filtered_attrs,
+        frozen,
+        slots,
+        pre_init,
+        pre_init_has_args,
+        post_init,
+        cache_hash,
+        base_attr_map,
+        is_exc,
+        needs_cached_setattr,
+        has_cls_on_setattr,
+        "__attrs_init__" if attrs_init else "__init__",
+    )
+    if cls.__module__ in sys.modules:
+        # This makes typing.get_type_hints(CLS.__init__) resolve string types.
+        globs.update(sys.modules[cls.__module__].__dict__)
+
+    globs.update({"NOTHING": NOTHING, "attr_dict": attr_dict})
+
+    if needs_cached_setattr:
+        # Save the lookup overhead in __init__ if we need to circumvent
+        # setattr hooks.
+        globs["_cached_setattr_get"] = _OBJ_SETATTR.__get__
+
+    return script, globs, annotations
+
+
+def _setattr(attr_name: str, value_var: str, has_on_setattr: bool) -> str:
+    """
+    Use the cached object.setattr to set *attr_name* to *value_var*.
+    """
+    return f"_setattr('{attr_name}', {value_var})"
+
+
+def _setattr_with_converter(
+    attr_name: str, value_var: str, has_on_setattr: bool, converter: Converter
+) -> str:
+    """
+    Use the cached object.setattr to set *attr_name* to *value_var*, but run
+    its converter first.
+    """
+    return f"_setattr('{attr_name}', {converter._fmt_converter_call(attr_name, value_var)})"
+
+
+def _assign(attr_name: str, value: str, has_on_setattr: bool) -> str:
+    """
+    Unless *attr_name* has an on_setattr hook, use normal assignment. Otherwise
+    relegate to _setattr.
+    """
+    if has_on_setattr:
+        return _setattr(attr_name, value, True)
+
+    return f"self.{attr_name} = {value}"
+
+
+def _assign_with_converter(
+    attr_name: str, value_var: str, has_on_setattr: bool, converter: Converter
+) -> str:
+    """
+    Unless *attr_name* has an on_setattr hook, use normal assignment after
+    conversion. Otherwise relegate to _setattr_with_converter.
+    """
+    if has_on_setattr:
+        return _setattr_with_converter(attr_name, value_var, True, converter)
+
+    return f"self.{attr_name} = {converter._fmt_converter_call(attr_name, value_var)}"
+
+
+def _determine_setters(
+    frozen: bool, slots: bool, base_attr_map: dict[str, type]
+):
+    """
+    Determine the correct setter functions based on whether a class is frozen
+    and/or slotted.
+    """
+    if frozen is True:
+        if slots is True:
+            return (), _setattr, _setattr_with_converter
+
+        # Dict frozen classes assign directly to __dict__.
+        # But only if the attribute doesn't come from an ancestor slot
+        # class.
+        # Note _inst_dict will be used again below if cache_hash is True
+
+        def fmt_setter(
+            attr_name: str, value_var: str, has_on_setattr: bool
+        ) -> str:
+            if _is_slot_attr(attr_name, base_attr_map):
+                return _setattr(attr_name, value_var, has_on_setattr)
+
+            return f"_inst_dict['{attr_name}'] = {value_var}"
+
+        def fmt_setter_with_converter(
+            attr_name: str,
+            value_var: str,
+            has_on_setattr: bool,
+            converter: Converter,
+        ) -> str:
+            if has_on_setattr or _is_slot_attr(attr_name, base_attr_map):
+                return _setattr_with_converter(
+                    attr_name, value_var, has_on_setattr, converter
+                )
+
+            return f"_inst_dict['{attr_name}'] = {converter._fmt_converter_call(attr_name, value_var)}"
+
+        return (
+            ("_inst_dict = self.__dict__",),
+            fmt_setter,
+            fmt_setter_with_converter,
+        )
+
+    # Not frozen -- we can just assign directly.
+    return (), _assign, _assign_with_converter
+
+
+def _attrs_to_init_script(
+    attrs: list[Attribute],
+    is_frozen: bool,
+    is_slotted: bool,
+    call_pre_init: bool,
+    pre_init_has_args: bool,
+    call_post_init: bool,
+    does_cache_hash: bool,
+    base_attr_map: dict[str, type],
+    is_exc: bool,
+    needs_cached_setattr: bool,
+    has_cls_on_setattr: bool,
+    method_name: str,
+) -> tuple[str, dict, dict]:
+    """
+    Return a script of an initializer for *attrs*, a dict of globals, and
+    annotations for the initializer.
+
+    The globals are required by the generated script.
+    """
+    lines = ["self.__attrs_pre_init__()"] if call_pre_init else []
+
+    if needs_cached_setattr:
+        lines.append(
+            # Circumvent the __setattr__ descriptor to save one lookup per
+            # assignment. Note _setattr will be used again below if
+            # does_cache_hash is True.
+            "_setattr = _cached_setattr_get(self)"
+        )
+
+    extra_lines, fmt_setter, fmt_setter_with_converter = _determine_setters(
+        is_frozen, is_slotted, base_attr_map
+    )
+    lines.extend(extra_lines)
+
+    args = []
+    kw_only_args = []
+    attrs_to_validate = []
+
+    # This is a dictionary of names to validator and converter callables.
+    # Injecting this into __init__ globals lets us avoid lookups.
+    names_for_globals = {}
+    annotations = {"return": None}
+
+    for a in attrs:
+        if a.validator:
+            attrs_to_validate.append(a)
+
+        attr_name = a.name
+        has_on_setattr = a.on_setattr is not None or (
+            a.on_setattr is not setters.NO_OP and has_cls_on_setattr
+        )
+        # a.alias is set to maybe-mangled attr_name in _ClassBuilder if not
+        # explicitly provided
+        arg_name = a.alias
+
+        has_factory = isinstance(a.default, Factory)
+        maybe_self = "self" if has_factory and a.default.takes_self else ""
+
+        if a.converter is not None and not isinstance(a.converter, Converter):
+            converter = Converter(a.converter)
+        else:
+            converter = a.converter
+
+        if a.init is False:
+            if has_factory:
+                init_factory_name = _INIT_FACTORY_PAT % (a.name,)
+                if converter is not None:
+                    lines.append(
+                        fmt_setter_with_converter(
+                            attr_name,
+                            init_factory_name + f"({maybe_self})",
+                            has_on_setattr,
+                            converter,
+                        )
+                    )
+                    names_for_globals[converter._get_global_name(a.name)] = (
+                        converter.converter
+                    )
+                else:
+                    lines.append(
+                        fmt_setter(
+                            attr_name,
+                            init_factory_name + f"({maybe_self})",
+                            has_on_setattr,
+                        )
+                    )
+                names_for_globals[init_factory_name] = a.default.factory
+            elif converter is not None:
+                lines.append(
+                    fmt_setter_with_converter(
+                        attr_name,
+                        f"attr_dict['{attr_name}'].default",
+                        has_on_setattr,
+                        converter,
+                    )
+                )
+                names_for_globals[converter._get_global_name(a.name)] = (
+                    converter.converter
+                )
+            else:
+                lines.append(
+                    fmt_setter(
+                        attr_name,
+                        f"attr_dict['{attr_name}'].default",
+                        has_on_setattr,
+                    )
+                )
+        elif a.default is not NOTHING and not has_factory:
+            arg = f"{arg_name}=attr_dict['{attr_name}'].default"
+            if a.kw_only:
+                kw_only_args.append(arg)
+            else:
+                args.append(arg)
+
+            if converter is not None:
+                lines.append(
+                    fmt_setter_with_converter(
+                        attr_name, arg_name, has_on_setattr, converter
+                    )
+                )
+                names_for_globals[converter._get_global_name(a.name)] = (
+                    converter.converter
+                )
+            else:
+                lines.append(fmt_setter(attr_name, arg_name, has_on_setattr))
+
+        elif has_factory:
+            arg = f"{arg_name}=NOTHING"
+            if a.kw_only:
+                kw_only_args.append(arg)
+            else:
+                args.append(arg)
+            lines.append(f"if {arg_name} is not NOTHING:")
+
+            init_factory_name = _INIT_FACTORY_PAT % (a.name,)
+            if converter is not None:
+                lines.append(
+                    "    "
+                    + fmt_setter_with_converter(
+                        attr_name, arg_name, has_on_setattr, converter
+                    )
+                )
+                lines.append("else:")
+                lines.append(
+                    "    "
+                    + fmt_setter_with_converter(
+                        attr_name,
+                        init_factory_name + "(" + maybe_self + ")",
+                        has_on_setattr,
+                        converter,
+                    )
+                )
+                names_for_globals[converter._get_global_name(a.name)] = (
+                    converter.converter
+                )
+            else:
+                lines.append(
+                    "    " + fmt_setter(attr_name, arg_name, has_on_setattr)
+                )
+                lines.append("else:")
+                lines.append(
+                    "    "
+                    + fmt_setter(
+                        attr_name,
+                        init_factory_name + "(" + maybe_self + ")",
+                        has_on_setattr,
+                    )
+                )
+            names_for_globals[init_factory_name] = a.default.factory
+        else:
+            if a.kw_only:
+                kw_only_args.append(arg_name)
+            else:
+                args.append(arg_name)
+
+            if converter is not None:
+                lines.append(
+                    fmt_setter_with_converter(
+                        attr_name, arg_name, has_on_setattr, converter
+                    )
+                )
+                names_for_globals[converter._get_global_name(a.name)] = (
+                    converter.converter
+                )
+            else:
+                lines.append(fmt_setter(attr_name, arg_name, has_on_setattr))
+
+        if a.init is True:
+            if a.type is not None and converter is None:
+                annotations[arg_name] = a.type
+            elif converter is not None and converter._first_param_type:
+                # Use the type from the converter if present.
+                annotations[arg_name] = converter._first_param_type
+
+    if attrs_to_validate:  # we can skip this if there are no validators.
+        names_for_globals["_config"] = _config
+        lines.append("if _config._run_validators is True:")
+        for a in attrs_to_validate:
+            val_name = "__attr_validator_" + a.name
+            attr_name = "__attr_" + a.name
+            lines.append(f"    {val_name}(self, {attr_name}, self.{a.name})")
+            names_for_globals[val_name] = a.validator
+            names_for_globals[attr_name] = a
+
+    if call_post_init:
+        lines.append("self.__attrs_post_init__()")
+
+    # Because this is set only after __attrs_post_init__ is called, a crash
+    # will result if post-init tries to access the hash code.  This seemed
+    # preferable to setting this beforehand, in which case alteration to field
+    # values during post-init combined with post-init accessing the hash code
+    # would result in silent bugs.
+    if does_cache_hash:
+        if is_frozen:
+            if is_slotted:
+                init_hash_cache = f"_setattr('{_HASH_CACHE_FIELD}', None)"
+            else:
+                init_hash_cache = f"_inst_dict['{_HASH_CACHE_FIELD}'] = None"
+        else:
+            init_hash_cache = f"self.{_HASH_CACHE_FIELD} = None"
+        lines.append(init_hash_cache)
+
+    # For exceptions we rely on BaseException.__init__ for proper
+    # initialization.
+    if is_exc:
+        vals = ",".join(f"self.{a.name}" for a in attrs if a.init)
+
+        lines.append(f"BaseException.__init__(self, {vals})")
+
+    args = ", ".join(args)
+    pre_init_args = args
+    if kw_only_args:
+        # leading comma & kw_only args
+        args += f"{', ' if args else ''}*, {', '.join(kw_only_args)}"
+        pre_init_kw_only_args = ", ".join(
+            [
+                f"{kw_arg_name}={kw_arg_name}"
+                # We need to remove the defaults from the kw_only_args.
+                for kw_arg_name in (kwa.split("=")[0] for kwa in kw_only_args)
+            ]
+        )
+        pre_init_args += ", " if pre_init_args else ""
+        pre_init_args += pre_init_kw_only_args
+
+    if call_pre_init and pre_init_has_args:
+        # If pre init method has arguments, pass same arguments as `__init__`.
+        lines[0] = f"self.__attrs_pre_init__({pre_init_args})"
+
+    # Python <3.12 doesn't allow backslashes in f-strings.
+    NL = "\n    "
+    return (
+        f"""def {method_name}(self, {args}):
+    {NL.join(lines) if lines else "pass"}
+""",
+        names_for_globals,
+        annotations,
+    )
+
+
+def _default_init_alias_for(name: str) -> str:
+    """
+    The default __init__ parameter name for a field.
+
+    This performs private-name adjustment via leading-unscore stripping,
+    and is the default value of Attribute.alias if not provided.
+    """
+
+    return name.lstrip("_")
+
+
+class Attribute:
+    """
+    *Read-only* representation of an attribute.
+
+    .. warning::
+
+       You should never instantiate this class yourself.
+
+    The class has *all* arguments of `attr.ib` (except for ``factory`` which is
+    only syntactic sugar for ``default=Factory(...)`` plus the following:
+
+    - ``name`` (`str`): The name of the attribute.
+    - ``alias`` (`str`): The __init__ parameter name of the attribute, after
+      any explicit overrides and default private-attribute-name handling.
+    - ``inherited`` (`bool`): Whether or not that attribute has been inherited
+      from a base class.
+    - ``eq_key`` and ``order_key`` (`typing.Callable` or `None`): The
+      callables that are used for comparing and ordering objects by this
+      attribute, respectively. These are set by passing a callable to
+      `attr.ib`'s ``eq``, ``order``, or ``cmp`` arguments. See also
+      :ref:`comparison customization <custom-comparison>`.
+
+    Instances of this class are frequently used for introspection purposes
+    like:
+
+    - `fields` returns a tuple of them.
+    - Validators get them passed as the first argument.
+    - The :ref:`field transformer <transform-fields>` hook receives a list of
+      them.
+    - The ``alias`` property exposes the __init__ parameter name of the field,
+      with any overrides and default private-attribute handling applied.
+
+
+    .. versionadded:: 20.1.0 *inherited*
+    .. versionadded:: 20.1.0 *on_setattr*
+    .. versionchanged:: 20.2.0 *inherited* is not taken into account for
+        equality checks and hashing anymore.
+    .. versionadded:: 21.1.0 *eq_key* and *order_key*
+    .. versionadded:: 22.2.0 *alias*
+
+    For the full version history of the fields, see `attr.ib`.
+    """
+
+    # These slots must NOT be reordered because we use them later for
+    # instantiation.
+    __slots__ = (  # noqa: RUF023
+        "name",
+        "default",
+        "validator",
+        "repr",
+        "eq",
+        "eq_key",
+        "order",
+        "order_key",
+        "hash",
+        "init",
+        "metadata",
+        "type",
+        "converter",
+        "kw_only",
+        "inherited",
+        "on_setattr",
+        "alias",
+    )
+
+    def __init__(
+        self,
+        name,
+        default,
+        validator,
+        repr,
+        cmp,  # XXX: unused, remove along with other cmp code.
+        hash,
+        init,
+        inherited,
+        metadata=None,
+        type=None,
+        converter=None,
+        kw_only=False,
+        eq=None,
+        eq_key=None,
+        order=None,
+        order_key=None,
+        on_setattr=None,
+        alias=None,
+    ):
+        eq, eq_key, order, order_key = _determine_attrib_eq_order(
+            cmp, eq_key or eq, order_key or order, True
+        )
+
+        # Cache this descriptor here to speed things up later.
+        bound_setattr = _OBJ_SETATTR.__get__(self)
+
+        # Despite the big red warning, people *do* instantiate `Attribute`
+        # themselves.
+        bound_setattr("name", name)
+        bound_setattr("default", default)
+        bound_setattr("validator", validator)
+        bound_setattr("repr", repr)
+        bound_setattr("eq", eq)
+        bound_setattr("eq_key", eq_key)
+        bound_setattr("order", order)
+        bound_setattr("order_key", order_key)
+        bound_setattr("hash", hash)
+        bound_setattr("init", init)
+        bound_setattr("converter", converter)
+        bound_setattr(
+            "metadata",
+            (
+                types.MappingProxyType(dict(metadata))  # Shallow copy
+                if metadata
+                else _EMPTY_METADATA_SINGLETON
+            ),
+        )
+        bound_setattr("type", type)
+        bound_setattr("kw_only", kw_only)
+        bound_setattr("inherited", inherited)
+        bound_setattr("on_setattr", on_setattr)
+        bound_setattr("alias", alias)
+
+    def __setattr__(self, name, value):
+        raise FrozenInstanceError
+
+    @classmethod
+    def from_counting_attr(cls, name: str, ca: _CountingAttr, type=None):
+        # type holds the annotated value. deal with conflicts:
+        if type is None:
+            type = ca.type
+        elif ca.type is not None:
+            msg = f"Type annotation and type argument cannot both be present for '{name}'."
+            raise ValueError(msg)
+        return cls(
+            name,
+            ca._default,
+            ca._validator,
+            ca.repr,
+            None,
+            ca.hash,
+            ca.init,
+            False,
+            ca.metadata,
+            type,
+            ca.converter,
+            ca.kw_only,
+            ca.eq,
+            ca.eq_key,
+            ca.order,
+            ca.order_key,
+            ca.on_setattr,
+            ca.alias,
+        )
+
+    # Don't use attrs.evolve since fields(Attribute) doesn't work
+    def evolve(self, **changes):
+        """
+        Copy *self* and apply *changes*.
+
+        This works similarly to `attrs.evolve` but that function does not work
+        with :class:`attrs.Attribute`.
+
+        It is mainly meant to be used for `transform-fields`.
+
+        .. versionadded:: 20.3.0
+        """
+        new = copy.copy(self)
+
+        new._setattrs(changes.items())
+
+        return new
+
+    # Don't use _add_pickle since fields(Attribute) doesn't work
+    def __getstate__(self):
+        """
+        Play nice with pickle.
+        """
+        return tuple(
+            getattr(self, name) if name != "metadata" else dict(self.metadata)
+            for name in self.__slots__
+        )
+
+    def __setstate__(self, state):
+        """
+        Play nice with pickle.
+        """
+        self._setattrs(zip(self.__slots__, state))
+
+    def _setattrs(self, name_values_pairs):
+        bound_setattr = _OBJ_SETATTR.__get__(self)
+        for name, value in name_values_pairs:
+            if name != "metadata":
+                bound_setattr(name, value)
+            else:
+                bound_setattr(
+                    name,
+                    (
+                        types.MappingProxyType(dict(value))
+                        if value
+                        else _EMPTY_METADATA_SINGLETON
+                    ),
+                )
+
+
+_a = [
+    Attribute(
+        name=name,
+        default=NOTHING,
+        validator=None,
+        repr=True,
+        cmp=None,
+        eq=True,
+        order=False,
+        hash=(name != "metadata"),
+        init=True,
+        inherited=False,
+        alias=_default_init_alias_for(name),
+    )
+    for name in Attribute.__slots__
+]
+
+Attribute = _add_hash(
+    _add_eq(
+        _add_repr(Attribute, attrs=_a),
+        attrs=[a for a in _a if a.name != "inherited"],
+    ),
+    attrs=[a for a in _a if a.hash and a.name != "inherited"],
+)
+
+
+class _CountingAttr:
+    """
+    Intermediate representation of attributes that uses a counter to preserve
+    the order in which the attributes have been defined.
+
+    *Internal* data structure of the attrs library.  Running into is most
+    likely the result of a bug like a forgotten `@attr.s` decorator.
+    """
+
+    __slots__ = (
+        "_default",
+        "_validator",
+        "alias",
+        "converter",
+        "counter",
+        "eq",
+        "eq_key",
+        "hash",
+        "init",
+        "kw_only",
+        "metadata",
+        "on_setattr",
+        "order",
+        "order_key",
+        "repr",
+        "type",
+    )
+    __attrs_attrs__ = (
+        *tuple(
+            Attribute(
+                name=name,
+                alias=_default_init_alias_for(name),
+                default=NOTHING,
+                validator=None,
+                repr=True,
+                cmp=None,
+                hash=True,
+                init=True,
+                kw_only=False,
+                eq=True,
+                eq_key=None,
+                order=False,
+                order_key=None,
+                inherited=False,
+                on_setattr=None,
+            )
+            for name in (
+                "counter",
+                "_default",
+                "repr",
+                "eq",
+                "order",
+                "hash",
+                "init",
+                "on_setattr",
+                "alias",
+            )
+        ),
+        Attribute(
+            name="metadata",
+            alias="metadata",
+            default=None,
+            validator=None,
+            repr=True,
+            cmp=None,
+            hash=False,
+            init=True,
+            kw_only=False,
+            eq=True,
+            eq_key=None,
+            order=False,
+            order_key=None,
+            inherited=False,
+            on_setattr=None,
+        ),
+    )
+    cls_counter = 0
+
+    def __init__(
+        self,
+        default,
+        validator,
+        repr,
+        cmp,
+        hash,
+        init,
+        converter,
+        metadata,
+        type,
+        kw_only,
+        eq,
+        eq_key,
+        order,
+        order_key,
+        on_setattr,
+        alias,
+    ):
+        _CountingAttr.cls_counter += 1
+        self.counter = _CountingAttr.cls_counter
+        self._default = default
+        self._validator = validator
+        self.converter = converter
+        self.repr = repr
+        self.eq = eq
+        self.eq_key = eq_key
+        self.order = order
+        self.order_key = order_key
+        self.hash = hash
+        self.init = init
+        self.metadata = metadata
+        self.type = type
+        self.kw_only = kw_only
+        self.on_setattr = on_setattr
+        self.alias = alias
+
+    def validator(self, meth):
+        """
+        Decorator that adds *meth* to the list of validators.
+
+        Returns *meth* unchanged.
+
+        .. versionadded:: 17.1.0
+        """
+        if self._validator is None:
+            self._validator = meth
+        else:
+            self._validator = and_(self._validator, meth)
+        return meth
+
+    def default(self, meth):
+        """
+        Decorator that allows to set the default for an attribute.
+
+        Returns *meth* unchanged.
+
+        Raises:
+            DefaultAlreadySetError: If default has been set before.
+
+        .. versionadded:: 17.1.0
+        """
+        if self._default is not NOTHING:
+            raise DefaultAlreadySetError
+
+        self._default = Factory(meth, takes_self=True)
+
+        return meth
+
+
+_CountingAttr = _add_eq(_add_repr(_CountingAttr))
+
+
+class Factory:
+    """
+    Stores a factory callable.
+
+    If passed as the default value to `attrs.field`, the factory is used to
+    generate a new value.
+
+    Args:
+        factory (typing.Callable):
+            A callable that takes either none or exactly one mandatory
+            positional argument depending on *takes_self*.
+
+        takes_self (bool):
+            Pass the partially initialized instance that is being initialized
+            as a positional argument.
+
+    .. versionadded:: 17.1.0  *takes_self*
+    """
+
+    __slots__ = ("factory", "takes_self")
+
+    def __init__(self, factory, takes_self=False):
+        self.factory = factory
+        self.takes_self = takes_self
+
+    def __getstate__(self):
+        """
+        Play nice with pickle.
+        """
+        return tuple(getattr(self, name) for name in self.__slots__)
+
+    def __setstate__(self, state):
+        """
+        Play nice with pickle.
+        """
+        for name, value in zip(self.__slots__, state):
+            setattr(self, name, value)
+
+
+_f = [
+    Attribute(
+        name=name,
+        default=NOTHING,
+        validator=None,
+        repr=True,
+        cmp=None,
+        eq=True,
+        order=False,
+        hash=True,
+        init=True,
+        inherited=False,
+    )
+    for name in Factory.__slots__
+]
+
+Factory = _add_hash(_add_eq(_add_repr(Factory, attrs=_f), attrs=_f), attrs=_f)
+
+
+class Converter:
+    """
+    Stores a converter callable.
+
+    Allows for the wrapped converter to take additional arguments. The
+    arguments are passed in the order they are documented.
+
+    Args:
+        converter (Callable): A callable that converts the passed value.
+
+        takes_self (bool):
+            Pass the partially initialized instance that is being initialized
+            as a positional argument. (default: `False`)
+
+        takes_field (bool):
+            Pass the field definition (an :class:`Attribute`) into the
+            converter as a positional argument. (default: `False`)
+
+    .. versionadded:: 24.1.0
+    """
+
+    __slots__ = (
+        "__call__",
+        "_first_param_type",
+        "_global_name",
+        "converter",
+        "takes_field",
+        "takes_self",
+    )
+
+    def __init__(self, converter, *, takes_self=False, takes_field=False):
+        self.converter = converter
+        self.takes_self = takes_self
+        self.takes_field = takes_field
+
+        ex = _AnnotationExtractor(converter)
+        self._first_param_type = ex.get_first_param_type()
+
+        if not (self.takes_self or self.takes_field):
+            self.__call__ = lambda value, _, __: self.converter(value)
+        elif self.takes_self and not self.takes_field:
+            self.__call__ = lambda value, instance, __: self.converter(
+                value, instance
+            )
+        elif not self.takes_self and self.takes_field:
+            self.__call__ = lambda value, __, field: self.converter(
+                value, field
+            )
+        else:
+            self.__call__ = lambda value, instance, field: self.converter(
+                value, instance, field
+            )
+
+        rt = ex.get_return_type()
+        if rt is not None:
+            self.__call__.__annotations__["return"] = rt
+
+    @staticmethod
+    def _get_global_name(attr_name: str) -> str:
+        """
+        Return the name that a converter for an attribute name *attr_name*
+        would have.
+        """
+        return f"__attr_converter_{attr_name}"
+
+    def _fmt_converter_call(self, attr_name: str, value_var: str) -> str:
+        """
+        Return a string that calls the converter for an attribute name
+        *attr_name* and the value in variable named *value_var* according to
+        `self.takes_self` and `self.takes_field`.
+        """
+        if not (self.takes_self or self.takes_field):
+            return f"{self._get_global_name(attr_name)}({value_var})"
+
+        if self.takes_self and self.takes_field:
+            return f"{self._get_global_name(attr_name)}({value_var}, self, attr_dict['{attr_name}'])"
+
+        if self.takes_self:
+            return f"{self._get_global_name(attr_name)}({value_var}, self)"
+
+        return f"{self._get_global_name(attr_name)}({value_var}, attr_dict['{attr_name}'])"
+
+    def __getstate__(self):
+        """
+        Return a dict containing only converter and takes_self -- the rest gets
+        computed when loading.
+        """
+        return {
+            "converter": self.converter,
+            "takes_self": self.takes_self,
+            "takes_field": self.takes_field,
+        }
+
+    def __setstate__(self, state):
+        """
+        Load instance from state.
+        """
+        self.__init__(**state)
+
+
+_f = [
+    Attribute(
+        name=name,
+        default=NOTHING,
+        validator=None,
+        repr=True,
+        cmp=None,
+        eq=True,
+        order=False,
+        hash=True,
+        init=True,
+        inherited=False,
+    )
+    for name in ("converter", "takes_self", "takes_field")
+]
+
+Converter = _add_hash(
+    _add_eq(_add_repr(Converter, attrs=_f), attrs=_f), attrs=_f
+)
+
+
+def make_class(
+    name, attrs, bases=(object,), class_body=None, **attributes_arguments
+):
+    r"""
+    A quick way to create a new class called *name* with *attrs*.
+
+    .. note::
+
+        ``make_class()`` is a thin wrapper around `attr.s`, not `attrs.define`
+        which means that it doesn't come with some of the improved defaults.
+
+        For example, if you want the same ``on_setattr`` behavior as in
+        `attrs.define`, you have to pass the hooks yourself: ``make_class(...,
+        on_setattr=setters.pipe(setters.convert, setters.validate)``
+
+    .. warning::
+
+        It is *your* duty to ensure that the class name and the attribute names
+        are valid identifiers. ``make_class()`` will *not* validate them for
+        you.
+
+    Args:
+        name (str): The name for the new class.
+
+        attrs (list | dict):
+            A list of names or a dictionary of mappings of names to `attr.ib`\
+            s / `attrs.field`\ s.
+
+            The order is deduced from the order of the names or attributes
+            inside *attrs*.  Otherwise the order of the definition of the
+            attributes is used.
+
+        bases (tuple[type, ...]): Classes that the new class will subclass.
+
+        class_body (dict):
+            An optional dictionary of class attributes for the new class.
+
+        attributes_arguments: Passed unmodified to `attr.s`.
+
+    Returns:
+        type: A new class with *attrs*.
+
+    .. versionadded:: 17.1.0 *bases*
+    .. versionchanged:: 18.1.0 If *attrs* is ordered, the order is retained.
+    .. versionchanged:: 23.2.0 *class_body*
+    .. versionchanged:: 25.2.0 Class names can now be unicode.
+    """
+    # Class identifiers are converted into the normal form NFKC while parsing
+    name = unicodedata.normalize("NFKC", name)
+
+    if isinstance(attrs, dict):
+        cls_dict = attrs
+    elif isinstance(attrs, (list, tuple)):
+        cls_dict = {a: attrib() for a in attrs}
+    else:
+        msg = "attrs argument must be a dict or a list."
+        raise TypeError(msg)
+
+    pre_init = cls_dict.pop("__attrs_pre_init__", None)
+    post_init = cls_dict.pop("__attrs_post_init__", None)
+    user_init = cls_dict.pop("__init__", None)
+
+    body = {}
+    if class_body is not None:
+        body.update(class_body)
+    if pre_init is not None:
+        body["__attrs_pre_init__"] = pre_init
+    if post_init is not None:
+        body["__attrs_post_init__"] = post_init
+    if user_init is not None:
+        body["__init__"] = user_init
+
+    type_ = types.new_class(name, bases, {}, lambda ns: ns.update(body))
+
+    # For pickling to work, the __module__ variable needs to be set to the
+    # frame where the class is created.  Bypass this step in environments where
+    # sys._getframe is not defined (Jython for example) or sys._getframe is not
+    # defined for arguments greater than 0 (IronPython).
+    with contextlib.suppress(AttributeError, ValueError):
+        type_.__module__ = sys._getframe(1).f_globals.get(
+            "__name__", "__main__"
+        )
+
+    # We do it here for proper warnings with meaningful stacklevel.
+    cmp = attributes_arguments.pop("cmp", None)
+    (
+        attributes_arguments["eq"],
+        attributes_arguments["order"],
+    ) = _determine_attrs_eq_order(
+        cmp,
+        attributes_arguments.get("eq"),
+        attributes_arguments.get("order"),
+        True,
+    )
+
+    cls = _attrs(these=cls_dict, **attributes_arguments)(type_)
+    # Only add type annotations now or "_attrs()" will complain:
+    cls.__annotations__ = {
+        k: v.type for k, v in cls_dict.items() if v.type is not None
+    }
+    return cls
+
+
+# These are required by within this module so we define them here and merely
+# import into .validators / .converters.
+
+
+@attrs(slots=True, unsafe_hash=True)
+class _AndValidator:
+    """
+    Compose many validators to a single one.
+    """
+
+    _validators = attrib()
+
+    def __call__(self, inst, attr, value):
+        for v in self._validators:
+            v(inst, attr, value)
+
+
+def and_(*validators):
+    """
+    A validator that composes multiple validators into one.
+
+    When called on a value, it runs all wrapped validators.
+
+    Args:
+        validators (~collections.abc.Iterable[typing.Callable]):
+            Arbitrary number of validators.
+
+    .. versionadded:: 17.1.0
+    """
+    vals = []
+    for validator in validators:
+        vals.extend(
+            validator._validators
+            if isinstance(validator, _AndValidator)
+            else [validator]
+        )
+
+    return _AndValidator(tuple(vals))
+
+
+def pipe(*converters):
+    """
+    A converter that composes multiple converters into one.
+
+    When called on a value, it runs all wrapped converters, returning the
+    *last* value.
+
+    Type annotations will be inferred from the wrapped converters', if they
+    have any.
+
+        converters (~collections.abc.Iterable[typing.Callable]):
+            Arbitrary number of converters.
+
+    .. versionadded:: 20.1.0
+    """
+
+    return_instance = any(isinstance(c, Converter) for c in converters)
+
+    if return_instance:
+
+        def pipe_converter(val, inst, field):
+            for c in converters:
+                val = (
+                    c(val, inst, field) if isinstance(c, Converter) else c(val)
+                )
+
+            return val
+
+    else:
+
+        def pipe_converter(val):
+            for c in converters:
+                val = c(val)
+
+            return val
+
+    if not converters:
+        # If the converter list is empty, pipe_converter is the identity.
+        A = TypeVar("A")
+        pipe_converter.__annotations__.update({"val": A, "return": A})
+    else:
+        # Get parameter type from first converter.
+        t = _AnnotationExtractor(converters[0]).get_first_param_type()
+        if t:
+            pipe_converter.__annotations__["val"] = t
+
+        last = converters[-1]
+        if not PY_3_11_PLUS and isinstance(last, Converter):
+            last = last.__call__
+
+        # Get return type from last converter.
+        rt = _AnnotationExtractor(last).get_return_type()
+        if rt:
+            pipe_converter.__annotations__["return"] = rt
+
+    if return_instance:
+        return Converter(pipe_converter, takes_self=True, takes_field=True)
+    return pipe_converter

venv/Lib/site-packages/attr/_next_gen.py

@@ -0,0 +1,623 @@
+# SPDX-License-Identifier: MIT
+
+"""
+These are keyword-only APIs that call `attr.s` and `attr.ib` with different
+default values.
+"""
+
+from functools import partial
+
+from . import setters
+from ._funcs import asdict as _asdict
+from ._funcs import astuple as _astuple
+from ._make import (
+    _DEFAULT_ON_SETATTR,
+    NOTHING,
+    _frozen_setattrs,
+    attrib,
+    attrs,
+)
+from .exceptions import UnannotatedAttributeError
+
+
+def define(
+    maybe_cls=None,
+    *,
+    these=None,
+    repr=None,
+    unsafe_hash=None,
+    hash=None,
+    init=None,
+    slots=True,
+    frozen=False,
+    weakref_slot=True,
+    str=False,
+    auto_attribs=None,
+    kw_only=False,
+    cache_hash=False,
+    auto_exc=True,
+    eq=None,
+    order=False,
+    auto_detect=True,
+    getstate_setstate=None,
+    on_setattr=None,
+    field_transformer=None,
+    match_args=True,
+):
+    r"""
+    A class decorator that adds :term:`dunder methods` according to
+    :term:`fields <field>` specified using :doc:`type annotations <types>`,
+    `field()` calls, or the *these* argument.
+
+    Since *attrs* patches or replaces an existing class, you cannot use
+    `object.__init_subclass__` with *attrs* classes, because it runs too early.
+    As a replacement, you can define ``__attrs_init_subclass__`` on your class.
+    It will be called by *attrs* classes that subclass it after they're
+    created. See also :ref:`init-subclass`.
+
+    Args:
+        slots (bool):
+            Create a :term:`slotted class <slotted classes>` that's more
+            memory-efficient. Slotted classes are generally superior to the
+            default dict classes, but have some gotchas you should know about,
+            so we encourage you to read the :term:`glossary entry <slotted
+            classes>`.
+
+        auto_detect (bool):
+            Instead of setting the *init*, *repr*, *eq*, and *hash* arguments
+            explicitly, assume they are set to True **unless any** of the
+            involved methods for one of the arguments is implemented in the
+            *current* class (meaning, it is *not* inherited from some base
+            class).
+
+            So, for example by implementing ``__eq__`` on a class yourself,
+            *attrs* will deduce ``eq=False`` and will create *neither*
+            ``__eq__`` *nor* ``__ne__`` (but Python classes come with a
+            sensible ``__ne__`` by default, so it *should* be enough to only
+            implement ``__eq__`` in most cases).
+
+            Passing True or False` to *init*, *repr*, *eq*, or *hash*
+            overrides whatever *auto_detect* would determine.
+
+        auto_exc (bool):
+            If the class subclasses `BaseException` (which implicitly includes
+            any subclass of any exception), the following happens to behave
+            like a well-behaved Python exception class:
+
+            - the values for *eq*, *order*, and *hash* are ignored and the
+              instances compare and hash by the instance's ids [#]_ ,
+            - all attributes that are either passed into ``__init__`` or have a
+              default value are additionally available as a tuple in the
+              ``args`` attribute,
+            - the value of *str* is ignored leaving ``__str__`` to base
+              classes.
+
+            .. [#]
+               Note that *attrs* will *not* remove existing implementations of
+               ``__hash__`` or the equality methods. It just won't add own
+               ones.
+
+        on_setattr (~typing.Callable | list[~typing.Callable] | None | ~typing.Literal[attrs.setters.NO_OP]):
+            A callable that is run whenever the user attempts to set an
+            attribute (either by assignment like ``i.x = 42`` or by using
+            `setattr` like ``setattr(i, "x", 42)``). It receives the same
+            arguments as validators: the instance, the attribute that is being
+            modified, and the new value.
+
+            If no exception is raised, the attribute is set to the return value
+            of the callable.
+
+            If a list of callables is passed, they're automatically wrapped in
+            an `attrs.setters.pipe`.
+
+            If left None, the default behavior is to run converters and
+            validators whenever an attribute is set.
+
+        init (bool):
+            Create a ``__init__`` method that initializes the *attrs*
+            attributes. Leading underscores are stripped for the argument name,
+            unless an alias is set on the attribute.
+
+            .. seealso::
+                `init` shows advanced ways to customize the generated
+                ``__init__`` method, including executing code before and after.
+
+        repr(bool):
+            Create a ``__repr__`` method with a human readable representation
+            of *attrs* attributes.
+
+        str (bool):
+            Create a ``__str__`` method that is identical to ``__repr__``. This
+            is usually not necessary except for `Exception`\ s.
+
+        eq (bool | None):
+            If True or None (default), add ``__eq__`` and ``__ne__`` methods
+            that check two instances for equality.
+
+            .. seealso::
+                `comparison` describes how to customize the comparison behavior
+                going as far comparing NumPy arrays.
+
+        order (bool | None):
+            If True, add ``__lt__``, ``__le__``, ``__gt__``, and ``__ge__``
+            methods that behave like *eq* above and allow instances to be
+            ordered.
+
+            They compare the instances as if they were tuples of their *attrs*
+            attributes if and only if the types of both classes are
+            *identical*.
+
+            If `None` mirror value of *eq*.
+
+            .. seealso:: `comparison`
+
+        unsafe_hash (bool | None):
+            If None (default), the ``__hash__`` method is generated according
+            how *eq* and *frozen* are set.
+
+            1. If *both* are True, *attrs* will generate a ``__hash__`` for
+               you.
+            2. If *eq* is True and *frozen* is False, ``__hash__`` will be set
+               to None, marking it unhashable (which it is).
+            3. If *eq* is False, ``__hash__`` will be left untouched meaning
+               the ``__hash__`` method of the base class will be used. If the
+               base class is `object`, this means it will fall back to id-based
+               hashing.
+
+            Although not recommended, you can decide for yourself and force
+            *attrs* to create one (for example, if the class is immutable even
+            though you didn't freeze it programmatically) by passing True or
+            not.  Both of these cases are rather special and should be used
+            carefully.
+
+            .. seealso::
+
+                - Our documentation on `hashing`,
+                - Python's documentation on `object.__hash__`,
+                - and the `GitHub issue that led to the default \ behavior
+                  <https://github.com/python-attrs/attrs/issues/136>`_ for more
+                  details.
+
+        hash (bool | None):
+            Deprecated alias for *unsafe_hash*. *unsafe_hash* takes precedence.
+
+        cache_hash (bool):
+            Ensure that the object's hash code is computed only once and stored
+            on the object.  If this is set to True, hashing must be either
+            explicitly or implicitly enabled for this class.  If the hash code
+            is cached, avoid any reassignments of fields involved in hash code
+            computation or mutations of the objects those fields point to after
+            object creation.  If such changes occur, the behavior of the
+            object's hash code is undefined.
+
+        frozen (bool):
+            Make instances immutable after initialization.  If someone attempts
+            to modify a frozen instance, `attrs.exceptions.FrozenInstanceError`
+            is raised.
+
+            .. note::
+
+                1. This is achieved by installing a custom ``__setattr__``
+                   method on your class, so you can't implement your own.
+
+                2. True immutability is impossible in Python.
+
+                3. This *does* have a minor a runtime performance `impact
+                   <how-frozen>` when initializing new instances.  In other
+                   words: ``__init__`` is slightly slower with ``frozen=True``.
+
+                4. If a class is frozen, you cannot modify ``self`` in
+                   ``__attrs_post_init__`` or a self-written ``__init__``. You
+                   can circumvent that limitation by using
+                   ``object.__setattr__(self, "attribute_name", value)``.
+
+                5. Subclasses of a frozen class are frozen too.
+
+        kw_only (bool):
+            Make all attributes keyword-only in the generated ``__init__`` (if
+            *init* is False, this parameter is ignored).
+
+        weakref_slot (bool):
+            Make instances weak-referenceable.  This has no effect unless
+            *slots* is True.
+
+        field_transformer (~typing.Callable | None):
+            A function that is called with the original class object and all
+            fields right before *attrs* finalizes the class.  You can use this,
+            for example, to automatically add converters or validators to
+            fields based on their types.
+
+            .. seealso:: `transform-fields`
+
+        match_args (bool):
+            If True (default), set ``__match_args__`` on the class to support
+            :pep:`634` (*Structural Pattern Matching*). It is a tuple of all
+            non-keyword-only ``__init__`` parameter names on Python 3.10 and
+            later. Ignored on older Python versions.
+
+        collect_by_mro (bool):
+            If True, *attrs* collects attributes from base classes correctly
+            according to the `method resolution order
+            <https://docs.python.org/3/howto/mro.html>`_. If False, *attrs*
+            will mimic the (wrong) behavior of `dataclasses` and :pep:`681`.
+
+            See also `issue #428
+            <https://github.com/python-attrs/attrs/issues/428>`_.
+
+        getstate_setstate (bool | None):
+            .. note::
+
+                This is usually only interesting for slotted classes and you
+                should probably just set *auto_detect* to True.
+
+            If True, ``__getstate__`` and ``__setstate__`` are generated and
+            attached to the class. This is necessary for slotted classes to be
+            pickleable. If left None, it's True by default for slotted classes
+            and False for dict classes.
+
+            If *auto_detect* is True, and *getstate_setstate* is left None, and
+            **either** ``__getstate__`` or ``__setstate__`` is detected
+            directly on the class (meaning: not inherited), it is set to False
+            (this is usually what you want).
+
+        auto_attribs (bool | None):
+            If True, look at type annotations to determine which attributes to
+            use, like `dataclasses`. If False, it will only look for explicit
+            :func:`field` class attributes, like classic *attrs*.
+
+            If left None, it will guess:
+
+            1. If any attributes are annotated and no unannotated
+               `attrs.field`\ s are found, it assumes *auto_attribs=True*.
+            2. Otherwise it assumes *auto_attribs=False* and tries to collect
+               `attrs.field`\ s.
+
+            If *attrs* decides to look at type annotations, **all** fields
+            **must** be annotated. If *attrs* encounters a field that is set to
+            a :func:`field` / `attr.ib` but lacks a type annotation, an
+            `attrs.exceptions.UnannotatedAttributeError` is raised.  Use
+            ``field_name: typing.Any = field(...)`` if you don't want to set a
+            type.
+
+            .. warning::
+
+                For features that use the attribute name to create decorators
+                (for example, :ref:`validators <validators>`), you still *must*
+                assign :func:`field` / `attr.ib` to them. Otherwise Python will
+                either not find the name or try to use the default value to
+                call, for example, ``validator`` on it.
+
+            Attributes annotated as `typing.ClassVar`, and attributes that are
+            neither annotated nor set to an `field()` are **ignored**.
+
+        these (dict[str, object]):
+            A dictionary of name to the (private) return value of `field()`
+            mappings. This is useful to avoid the definition of your attributes
+            within the class body because you can't (for example, if you want
+            to add ``__repr__`` methods to Django models) or don't want to.
+
+            If *these* is not `None`, *attrs* will *not* search the class body
+            for attributes and will *not* remove any attributes from it.
+
+            The order is deduced from the order of the attributes inside
+            *these*.
+
+            Arguably, this is a rather obscure feature.
+
+    .. versionadded:: 20.1.0
+    .. versionchanged:: 21.3.0 Converters are also run ``on_setattr``.
+    .. versionadded:: 22.2.0
+       *unsafe_hash* as an alias for *hash* (for :pep:`681` compliance).
+    .. versionchanged:: 24.1.0
+       Instances are not compared as tuples of attributes anymore, but using a
+       big ``and`` condition. This is faster and has more correct behavior for
+       uncomparable values like `math.nan`.
+    .. versionadded:: 24.1.0
+       If a class has an *inherited* classmethod called
+       ``__attrs_init_subclass__``, it is executed after the class is created.
+    .. deprecated:: 24.1.0 *hash* is deprecated in favor of *unsafe_hash*.
+    .. versionadded:: 24.3.0
+       Unless already present, a ``__replace__`` method is automatically
+       created for `copy.replace` (Python 3.13+ only).
+
+    .. note::
+
+        The main differences to the classic `attr.s` are:
+
+        - Automatically detect whether or not *auto_attribs* should be `True`
+          (c.f. *auto_attribs* parameter).
+        - Converters and validators run when attributes are set by default --
+          if *frozen* is `False`.
+        - *slots=True*
+
+          Usually, this has only upsides and few visible effects in everyday
+          programming. But it *can* lead to some surprising behaviors, so
+          please make sure to read :term:`slotted classes`.
+
+        - *auto_exc=True*
+        - *auto_detect=True*
+        - *order=False*
+        - Some options that were only relevant on Python 2 or were kept around
+          for backwards-compatibility have been removed.
+
+    """
+
+    def do_it(cls, auto_attribs):
+        return attrs(
+            maybe_cls=cls,
+            these=these,
+            repr=repr,
+            hash=hash,
+            unsafe_hash=unsafe_hash,
+            init=init,
+            slots=slots,
+            frozen=frozen,
+            weakref_slot=weakref_slot,
+            str=str,
+            auto_attribs=auto_attribs,
+            kw_only=kw_only,
+            cache_hash=cache_hash,
+            auto_exc=auto_exc,
+            eq=eq,
+            order=order,
+            auto_detect=auto_detect,
+            collect_by_mro=True,
+            getstate_setstate=getstate_setstate,
+            on_setattr=on_setattr,
+            field_transformer=field_transformer,
+            match_args=match_args,
+        )
+
+    def wrap(cls):
+        """
+        Making this a wrapper ensures this code runs during class creation.
+
+        We also ensure that frozen-ness of classes is inherited.
+        """
+        nonlocal frozen, on_setattr
+
+        had_on_setattr = on_setattr not in (None, setters.NO_OP)
+
+        # By default, mutable classes convert & validate on setattr.
+        if frozen is False and on_setattr is None:
+            on_setattr = _DEFAULT_ON_SETATTR
+
+        # However, if we subclass a frozen class, we inherit the immutability
+        # and disable on_setattr.
+        for base_cls in cls.__bases__:
+            if base_cls.__setattr__ is _frozen_setattrs:
+                if had_on_setattr:
+                    msg = "Frozen classes can't use on_setattr (frozen-ness was inherited)."
+                    raise ValueError(msg)
+
+                on_setattr = setters.NO_OP
+                break
+
+        if auto_attribs is not None:
+            return do_it(cls, auto_attribs)
+
+        try:
+            return do_it(cls, True)
+        except UnannotatedAttributeError:
+            return do_it(cls, False)
+
+    # maybe_cls's type depends on the usage of the decorator.  It's a class
+    # if it's used as `@attrs` but `None` if used as `@attrs()`.
+    if maybe_cls is None:
+        return wrap
+
+    return wrap(maybe_cls)
+
+
+mutable = define
+frozen = partial(define, frozen=True, on_setattr=None)
+
+
+def field(
+    *,
+    default=NOTHING,
+    validator=None,
+    repr=True,
+    hash=None,
+    init=True,
+    metadata=None,
+    type=None,
+    converter=None,
+    factory=None,
+    kw_only=False,
+    eq=None,
+    order=None,
+    on_setattr=None,
+    alias=None,
+):
+    """
+    Create a new :term:`field` / :term:`attribute` on a class.
+
+    ..  warning::
+
+        Does **nothing** unless the class is also decorated with
+        `attrs.define` (or similar)!
+
+    Args:
+        default:
+            A value that is used if an *attrs*-generated ``__init__`` is used
+            and no value is passed while instantiating or the attribute is
+            excluded using ``init=False``.
+
+            If the value is an instance of `attrs.Factory`, its callable will
+            be used to construct a new value (useful for mutable data types
+            like lists or dicts).
+
+            If a default is not set (or set manually to `attrs.NOTHING`), a
+            value *must* be supplied when instantiating; otherwise a
+            `TypeError` will be raised.
+
+            .. seealso:: `defaults`
+
+        factory (~typing.Callable):
+            Syntactic sugar for ``default=attr.Factory(factory)``.
+
+        validator (~typing.Callable | list[~typing.Callable]):
+            Callable that is called by *attrs*-generated ``__init__`` methods
+            after the instance has been initialized.  They receive the
+            initialized instance, the :func:`~attrs.Attribute`, and the passed
+            value.
+
+            The return value is *not* inspected so the validator has to throw
+            an exception itself.
+
+            If a `list` is passed, its items are treated as validators and must
+            all pass.
+
+            Validators can be globally disabled and re-enabled using
+            `attrs.validators.get_disabled` / `attrs.validators.set_disabled`.
+
+            The validator can also be set using decorator notation as shown
+            below.
+
+            .. seealso:: :ref:`validators`
+
+        repr (bool | ~typing.Callable):
+            Include this attribute in the generated ``__repr__`` method. If
+            True, include the attribute; if False, omit it. By default, the
+            built-in ``repr()`` function is used. To override how the attribute
+            value is formatted, pass a ``callable`` that takes a single value
+            and returns a string. Note that the resulting string is used as-is,
+            which means it will be used directly *instead* of calling
+            ``repr()`` (the default).
+
+        eq (bool | ~typing.Callable):
+            If True (default), include this attribute in the generated
+            ``__eq__`` and ``__ne__`` methods that check two instances for
+            equality. To override how the attribute value is compared, pass a
+            callable that takes a single value and returns the value to be
+            compared.
+
+            .. seealso:: `comparison`
+
+        order (bool | ~typing.Callable):
+            If True (default), include this attributes in the generated
+            ``__lt__``, ``__le__``, ``__gt__`` and ``__ge__`` methods. To
+            override how the attribute value is ordered, pass a callable that
+            takes a single value and returns the value to be ordered.
+
+            .. seealso:: `comparison`
+
+        hash (bool | None):
+            Include this attribute in the generated ``__hash__`` method.  If
+            None (default), mirror *eq*'s value.  This is the correct behavior
+            according the Python spec.  Setting this value to anything else
+            than None is *discouraged*.
+
+            .. seealso:: `hashing`
+
+        init (bool):
+            Include this attribute in the generated ``__init__`` method.
+
+            It is possible to set this to False and set a default value. In
+            that case this attributed is unconditionally initialized with the
+            specified default value or factory.
+
+            .. seealso:: `init`
+
+        converter (typing.Callable | Converter):
+            A callable that is called by *attrs*-generated ``__init__`` methods
+            to convert attribute's value to the desired format.
+
+            If a vanilla callable is passed, it is given the passed-in value as
+            the only positional argument. It is possible to receive additional
+            arguments by wrapping the callable in a `Converter`.
+
+            Either way, the returned value will be used as the new value of the
+            attribute.  The value is converted before being passed to the
+            validator, if any.
+
+            .. seealso:: :ref:`converters`
+
+        metadata (dict | None):
+            An arbitrary mapping, to be used by third-party code.
+
+            .. seealso:: `extending-metadata`.
+
+        type (type):
+            The type of the attribute. Nowadays, the preferred method to
+            specify the type is using a variable annotation (see :pep:`526`).
+            This argument is provided for backwards-compatibility and for usage
+            with `make_class`. Regardless of the approach used, the type will
+            be stored on ``Attribute.type``.
+
+            Please note that *attrs* doesn't do anything with this metadata by
+            itself. You can use it as part of your own code or for `static type
+            checking <types>`.
+
+        kw_only (bool):
+            Make this attribute keyword-only in the generated ``__init__`` (if
+            ``init`` is False, this parameter is ignored).
+
+        on_setattr (~typing.Callable | list[~typing.Callable] | None | ~typing.Literal[attrs.setters.NO_OP]):
+            Allows to overwrite the *on_setattr* setting from `attr.s`. If left
+            None, the *on_setattr* value from `attr.s` is used. Set to
+            `attrs.setters.NO_OP` to run **no** `setattr` hooks for this
+            attribute -- regardless of the setting in `define()`.
+
+        alias (str | None):
+            Override this attribute's parameter name in the generated
+            ``__init__`` method. If left None, default to ``name`` stripped
+            of leading underscores. See `private-attributes`.
+
+    .. versionadded:: 20.1.0
+    .. versionchanged:: 21.1.0
+       *eq*, *order*, and *cmp* also accept a custom callable
+    .. versionadded:: 22.2.0 *alias*
+    .. versionadded:: 23.1.0
+       The *type* parameter has been re-added; mostly for `attrs.make_class`.
+       Please note that type checkers ignore this metadata.
+
+    .. seealso::
+
+       `attr.ib`
+    """
+    return attrib(
+        default=default,
+        validator=validator,
+        repr=repr,
+        hash=hash,
+        init=init,
+        metadata=metadata,
+        type=type,
+        converter=converter,
+        factory=factory,
+        kw_only=kw_only,
+        eq=eq,
+        order=order,
+        on_setattr=on_setattr,
+        alias=alias,
+    )
+
+
+def asdict(inst, *, recurse=True, filter=None, value_serializer=None):
+    """
+    Same as `attr.asdict`, except that collections types are always retained
+    and dict is always used as *dict_factory*.
+
+    .. versionadded:: 21.3.0
+    """
+    return _asdict(
+        inst=inst,
+        recurse=recurse,
+        filter=filter,
+        value_serializer=value_serializer,
+        retain_collection_types=True,
+    )
+
+
+def astuple(inst, *, recurse=True, filter=None):
+    """
+    Same as `attr.astuple`, except that collections types are always retained
+    and `tuple` is always used as the *tuple_factory*.
+
+    .. versionadded:: 21.3.0
+    """
+    return _astuple(
+        inst=inst, recurse=recurse, filter=filter, retain_collection_types=True
+    )

venv/Lib/site-packages/attr/_typing_compat.pyi

@@ -0,0 +1,15 @@
+from typing import Any, ClassVar, Protocol
+
+# MYPY is a special constant in mypy which works the same way as `TYPE_CHECKING`.
+MYPY = False
+
+if MYPY:
+    # A protocol to be able to statically accept an attrs class.
+    class AttrsInstance_(Protocol):
+        __attrs_attrs__: ClassVar[Any]
+
+else:
+    # For type checkers without plug-in support use an empty protocol that
+    # will (hopefully) be combined into a union.
+    class AttrsInstance_(Protocol):
+        pass

venv/Lib/site-packages/attr/_version_info.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: MIT
+
+
+from functools import total_ordering
+
+from ._funcs import astuple
+from ._make import attrib, attrs
+
+
+@total_ordering
+@attrs(eq=False, order=False, slots=True, frozen=True)
+class VersionInfo:
+    """
+    A version object that can be compared to tuple of length 1--4:
+
+    >>> attr.VersionInfo(19, 1, 0, "final")  <= (19, 2)
+    True
+    >>> attr.VersionInfo(19, 1, 0, "final") < (19, 1, 1)
+    True
+    >>> vi = attr.VersionInfo(19, 2, 0, "final")
+    >>> vi < (19, 1, 1)
+    False
+    >>> vi < (19,)
+    False
+    >>> vi == (19, 2,)
+    True
+    >>> vi == (19, 2, 1)
+    False
+
+    .. versionadded:: 19.2
+    """
+
+    year = attrib(type=int)
+    minor = attrib(type=int)
+    micro = attrib(type=int)
+    releaselevel = attrib(type=str)
+
+    @classmethod
+    def _from_version_string(cls, s):
+        """
+        Parse *s* and return a _VersionInfo.
+        """
+        v = s.split(".")
+        if len(v) == 3:
+            v.append("final")
+
+        return cls(
+            year=int(v[0]), minor=int(v[1]), micro=int(v[2]), releaselevel=v[3]
+        )
+
+    def _ensure_tuple(self, other):
+        """
+        Ensure *other* is a tuple of a valid length.
+
+        Returns a possibly transformed *other* and ourselves as a tuple of
+        the same length as *other*.
+        """
+
+        if self.__class__ is other.__class__:
+            other = astuple(other)
+
+        if not isinstance(other, tuple):
+            raise NotImplementedError
+
+        if not (1 <= len(other) <= 4):
+            raise NotImplementedError
+
+        return astuple(self)[: len(other)], other
+
+    def __eq__(self, other):
+        try:
+            us, them = self._ensure_tuple(other)
+        except NotImplementedError:
+            return NotImplemented
+
+        return us == them
+
+    def __lt__(self, other):
+        try:
+            us, them = self._ensure_tuple(other)
+        except NotImplementedError:
+            return NotImplemented
+
+        # Since alphabetically "dev0" < "final" < "post1" < "post2", we don't
+        # have to do anything special with releaselevel for now.
+        return us < them

venv/Lib/site-packages/attr/_version_info.pyi

@@ -0,0 +1,9 @@
+class VersionInfo:
+    @property
+    def year(self) -> int: ...
+    @property
+    def minor(self) -> int: ...
+    @property
+    def micro(self) -> int: ...
+    @property
+    def releaselevel(self) -> str: ...