From 5cea8a03793c478b0917cc2a5faae64928f5ace6 Mon Sep 17 00:00:00 2001
From: xopherw
Date: Sat, 26 Jul 2025 15:55:43 +1000
Subject: [PATCH 1/2] rearranged sphinx footer using footer_start,
footer_center, footer_end
---
doc/_templates/pandas_footer.html | 2 +-
doc/source/conf.py | 4 +++-
2 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/doc/_templates/pandas_footer.html b/doc/_templates/pandas_footer.html
index 6d8caa4d6c741..9f8a2a2a4b945 100644
--- a/doc/_templates/pandas_footer.html
+++ b/doc/_templates/pandas_footer.html
@@ -1,3 +1,3 @@
© {{copyright}} pandas via NumFOCUS, Inc. Hosted by OVHcloud.
-
+
\ No newline at end of file
diff --git a/doc/source/conf.py b/doc/source/conf.py
index f222a228531ff..5e0c2c2849dab 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -242,7 +242,9 @@
html_theme_options = {
"external_links": [],
- "footer_start": ["pandas_footer", "sphinx-version"],
+ "footer_start": ["pandas_footer"],
+ "footer_center": ["sphinx-version"],
+ "footer_end": ["theme-version"],
"github_url": "https://github.com/pandas-dev/pandas",
"analytics": {
"plausible_analytics_domain": "pandas.pydata.org",
From 1500eac78133d5437309aebf4d57e4e1ce1cb846 Mon Sep 17 00:00:00 2001
From: xopherw
Date: Wed, 30 Jul 2025 11:40:39 +1000
Subject: [PATCH 2/2] without template
---
doc/source/conf.py | 15 +-
doc/source/development/community.rst | 123 ---
doc/source/development/contributing.rst | 341 ------
.../development/contributing_codebase.rst | 964 -----------------
.../development/contributing_docstring.rst | 999 ------------------
.../contributing_documentation.rst | 215 ----
.../development/contributing_environment.rst | 313 ------
.../development/contributing_gitpod.rst | 274 -----
doc/source/development/copy_on_write.rst | 42 -
.../development/debugging_extensions.rst | 63 --
doc/source/development/developer.rst | 187 ----
doc/source/development/extending.rst | 536 ----------
.../gitpod-imgs/gitpod-dashboard-stop.png | Bin 197766 -> 0 bytes
.../gitpod-edit-permissions-gh.png | Bin 112101 -> 0 bytes
.../gitpod-edit-permissions-repo.png | Bin 5505 -> 0 bytes
.../gitpod-imgs/gitpod-workspace.png | Bin 458725 -> 0 bytes
.../development/gitpod-imgs/pandas-github.png | Bin 5368 -> 0 bytes
.../gitpod-imgs/pandas-gitpod-branches.png | Bin 236991 -> 0 bytes
.../development/gitpod-imgs/rst-rendering.png | Bin 996327 -> 0 bytes
.../development/gitpod-imgs/vscode-rst.png | Bin 16443 -> 0 bytes
.../gitpod-imgs/vscode-statusbar.png | Bin 9351 -> 0 bytes
doc/source/development/index.rst | 26 -
doc/source/development/internals.rst | 78 --
doc/source/development/maintaining.rst | 510 ---------
doc/source/development/policies.rst | 61 --
setup.py | 686 ------------
26 files changed, 11 insertions(+), 5422 deletions(-)
delete mode 100644 doc/source/development/community.rst
delete mode 100644 doc/source/development/contributing.rst
delete mode 100644 doc/source/development/contributing_codebase.rst
delete mode 100644 doc/source/development/contributing_docstring.rst
delete mode 100644 doc/source/development/contributing_documentation.rst
delete mode 100644 doc/source/development/contributing_environment.rst
delete mode 100644 doc/source/development/contributing_gitpod.rst
delete mode 100644 doc/source/development/copy_on_write.rst
delete mode 100644 doc/source/development/debugging_extensions.rst
delete mode 100644 doc/source/development/developer.rst
delete mode 100644 doc/source/development/extending.rst
delete mode 100644 doc/source/development/gitpod-imgs/gitpod-dashboard-stop.png
delete mode 100644 doc/source/development/gitpod-imgs/gitpod-edit-permissions-gh.png
delete mode 100644 doc/source/development/gitpod-imgs/gitpod-edit-permissions-repo.png
delete mode 100644 doc/source/development/gitpod-imgs/gitpod-workspace.png
delete mode 100644 doc/source/development/gitpod-imgs/pandas-github.png
delete mode 100644 doc/source/development/gitpod-imgs/pandas-gitpod-branches.png
delete mode 100644 doc/source/development/gitpod-imgs/rst-rendering.png
delete mode 100644 doc/source/development/gitpod-imgs/vscode-rst.png
delete mode 100644 doc/source/development/gitpod-imgs/vscode-statusbar.png
delete mode 100644 doc/source/development/index.rst
delete mode 100644 doc/source/development/internals.rst
delete mode 100644 doc/source/development/maintaining.rst
delete mode 100644 doc/source/development/policies.rst
delete mode 100755 setup.py
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 5e0c2c2849dab..6070f5d84fb37 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -19,6 +19,7 @@
import warnings
import jinja2
+from markupsafe import Markup
from numpydoc.docscrape import NumpyDocString
from sphinx.ext.autosummary import _import_by_name
@@ -32,6 +33,9 @@
# Python's default allowed recursion depth is 1000.
sys.setrecursionlimit(5000)
+# Disable parallel reading to avoid multiprocessing issues on macOS
+parallel_read_safe = False
+
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -150,7 +154,7 @@
toggleprompt_offset_right = 35
# Add any paths that contain templates here, relative to this directory.
-templates_path = ["../_templates"]
+# templates_path = ["../_templates"]
# The suffix of source filenames.
source_suffix = [".rst"]
@@ -164,7 +168,7 @@
# General information about the project.
project = "pandas"
# We have our custom "pandas_footer.html" template, using copyright for the current year
-copyright = f"{datetime.now().year},"
+# copyright = f"{datetime.now().year},"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -240,11 +244,14 @@
# only keep major.minor version number to match versions.json
switcher_version = ".".join(version.split(".")[:2])
+# Simple copyright text - HTML links are handled in pandas_footer.html template
+copyright = Markup(f"{datetime.now().year}, pandas via NumFOCUS, Inc. Hosted by OVHcloud")
+
html_theme_options = {
- "external_links": [],
- "footer_start": ["pandas_footer"],
+ "footer_start": ["copyright"],
"footer_center": ["sphinx-version"],
"footer_end": ["theme-version"],
+ "external_links": [],
"github_url": "https://github.com/pandas-dev/pandas",
"analytics": {
"plausible_analytics_domain": "pandas.pydata.org",
diff --git a/doc/source/development/community.rst b/doc/source/development/community.rst
deleted file mode 100644
index e139ea0376771..0000000000000
--- a/doc/source/development/community.rst
+++ /dev/null
@@ -1,123 +0,0 @@
-.. _community:
-
-=====================
-Contributor community
-=====================
-
-pandas is a community-driven open source project developed by a large group
-of `contributors `_
-and a smaller group of `maintainers `_.
-The pandas leadership has made a strong commitment to creating an open,
-inclusive, and positive community. Please read the pandas `Code of Conduct
-`_ for guidance on how to
-interact with others in a way that makes the community thrive.
-
-We offer several meetings and communication channels to share knowledge and
-connect with others within the pandas community.
-
-Community meeting
------------------
-
-The pandas Community Meeting is a regular sync meeting for the project's
-maintainers which is open to the community. Everyone is welcome to attend and
-contribute to conversations.
-
-The meetings take place on the second and fourth Wednesdays of each month at 18:00 UTC.
-
-The minutes of past meetings are available in `this Google Document `__.
-
-
-New contributor meeting
------------------------
-
-On the third Wednesday of the month, we hold meetings to welcome and support
-new contributors in our community.
-
-| 👋 you all are invited
-| 💬 everyone can present (add yourself to the hackMD agenda)
-| 👀 anyone can sit in and listen
-
-Attendees are new and experienced contributors, as well as a few maintainers.
-We aim to answer questions about getting started, or help with work in
-progress when possible, as well as get to know each other and share our
-learnings and experiences.
-
-The agenda for the next meeting and minutes of past meetings are available in
-`this HackMD `__.
-
-Calendar
---------
-
-This calendar shows all the community meetings. Our community meetings are
-ideal for anyone wanting to contribute to pandas, or just curious to know how
-current development is going.
-
-.. raw:: html
-
-
-
-You can subscribe to this calendar with the following links:
-
-* `iCal `__
-* `Google calendar `__
-
-Additionally, we'll sometimes have one-off meetings on specific topics.
-These will be published on the same calendar.
-
-`GitHub issue tracker `_
-----------------------------------------------------------------------
-
-The pandas contributor community conducts conversations mainly via this channel.
-Any community member can open issues to:
-
-- Report bugs, e.g. "I noticed the behavior of a certain function is
- incorrect"
-- Request features, e.g. "I would like this error message to be more readable"
-- Request documentation improvements, e.g. "I found this section unclear"
-- Ask questions, e.g. "I noticed the behavior of a certain function
- changed between versions. Is this expected?".
-
- - Ideally, your questions should be related to how pandas works rather
- than how you use pandas. `StackOverflow `_ is
- better suited for answering usage questions, and we ask that all usage
- questions are first asked on StackOverflow. Thank you for respecting our
- time and wishes. 🙇
-
-Maintainers and frequent contributors might also open issues to discuss the
-ongoing development of the project. For example:
-
-- Report issues with the CI, GitHub Actions, or the performance of pandas
-- Open issues relating to the internals
-- Start roadmap discussion aligning on proposals for what to do in future
- releases or changes to the API.
-- Open issues relating to the project's website, logo, or governance
-
-The developer mailing list
---------------------------
-
-The pandas mailing list `pandas-dev@python.org `_ is used for long form
-conversations and to engage people in the wider community who might not
-be active on the issue tracker but we would like to include in discussions.
-
-Join the mailing list and view the archives `here `_.
-
-.. _community.slack:
-
-Community slack
----------------
-
-We have a chat platform for contributors, maintainers and potential
-contributors. This is not a space for user questions, rather for questions about
-contributing to pandas. The slack is a private space, specifically meant for
-people who are hesitant to bring up their questions or ideas on a large public
-mailing list or GitHub.
-
-If this sounds like the right place for you, you are welcome to join using
-`this link `_!
-Please remember to follow our `Code of Conduct `_,
-and be aware that our admins are monitoring for irrelevant messages and will remove folks who use
-our
-slack for spam, advertisements and messages not related to the pandas contributing community. And
-please remember that slack is not meant to replace the mailing list or issue tracker - all important
-announcements and conversations should still happen there.
diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst
deleted file mode 100644
index 66178a88e3e31..0000000000000
--- a/doc/source/development/contributing.rst
+++ /dev/null
@@ -1,341 +0,0 @@
-.. _contributing:
-
-{{ header }}
-
-**********************
-Contributing to pandas
-**********************
-
-.. contents:: Table of contents:
- :local:
-
-
-All contributions, bug reports, bug fixes, documentation improvements,
-enhancements, and ideas are welcome.
-
-.. _contributing.bug_reports:
-
-Bug reports and enhancement requests
-====================================
-
-Bug reports and enhancement requests are an important part of making pandas more stable and
-are curated though Github issues. When reporting an issue or request, please select the `appropriate
-category and fill out the issue form fully `_
-to ensure others and the core development team can fully understand the scope of the issue.
-
-The issue will then show up to the pandas community and be open to comments/ideas from others.
-
-Finding an issue to contribute to
-=================================
-
-If you are brand new to pandas or open-source development, we recommend searching
-the `GitHub "issues" tab `_
-to find issues that interest you. Unassigned issues labeled `Docs
-`_
-and `good first issue
-`_
-are typically good for newer contributors.
-
-Once you've found an interesting issue, it's a good idea to assign the issue to yourself,
-so nobody else duplicates the work on it. On the Github issue, a comment with the exact
-text ``take`` to automatically assign you the issue
-(this will take seconds and may require refreshing the page to see it).
-
-If for whatever reason you are not able to continue working with the issue, please
-unassign it, so other people know it's available again. You can check the list of
-assigned issues, since people may not be working in them anymore. If you want to work on one
-that is assigned, feel free to kindly ask the current assignee if you can take it
-(please allow at least a week of inactivity before considering work in the issue discontinued).
-
-We have several :ref:`contributor community ` communication channels, which you are
-welcome to join, and ask questions as you figure things out. Among them are regular meetings for
-new contributors, dev meetings, a dev mailing list, and a Slack for the contributor community.
-All pandas contributors are welcome to these spaces, where they can connect with each other. Even
-maintainers who have been with us for a long time felt just like you when they started out, and
-are happy to welcome you and support you as you get to know how we work, and where things are.
-Take a look at the next sections to learn more.
-
-.. _contributing.github:
-
-Submitting a pull request
-=========================
-
-.. _contributing.version_control:
-
-Version control, Git, and GitHub
---------------------------------
-
-pandas is hosted on `GitHub `_, and to
-contribute, you will need to sign up for a `free GitHub account
-`_. We use `Git `_ for
-version control to allow many people to work together on the project.
-
-If you are new to Git, you can reference some of these resources for learning Git. Feel free to reach out
-to the :ref:`contributor community ` for help if needed:
-
-* `Git documentation `_.
-
-Also, the project follows a forking workflow further described on this page whereby
-contributors fork the repository, make changes and then create a pull request.
-So please be sure to read and follow all the instructions in this guide.
-
-If you are new to contributing to projects through forking on GitHub,
-take a look at the `GitHub documentation for contributing to projects `_.
-GitHub provides a quick tutorial using a test repository that may help you become more familiar
-with forking a repository, cloning a fork, creating a feature branch, pushing changes and
-making pull requests.
-
-Below are some useful resources for learning more about forking and pull requests on GitHub:
-
-* the `GitHub documentation for forking a repo `_.
-* the `GitHub documentation for collaborating with pull requests `_.
-* the `GitHub documentation for working with forks `_.
-
-Getting started with Git
-------------------------
-
-`GitHub has instructions `__ for installing git,
-setting up your SSH key, and configuring git. All these steps need to be completed before
-you can work seamlessly between your local repository and GitHub.
-
-.. _contributing.forking:
-
-Create a fork of pandas
------------------------
-
-You will need your own copy of pandas (aka fork) to work on the code. Go to the `pandas project
-page `_ and hit the ``Fork`` button. Please uncheck the box to copy only the main branch before selecting ``Create Fork``.
-You will want to clone your fork to your machine
-
-.. code-block:: shell
-
- git clone https://github.com/your-user-name/pandas.git pandas-yourname
- cd pandas-yourname
- git remote add upstream https://github.com/pandas-dev/pandas.git
- git fetch upstream
-
-This creates the directory ``pandas-yourname`` and connects your repository to
-the upstream (main project) *pandas* repository.
-
-.. note::
-
- Performing a shallow clone (with ``--depth==N``, for some ``N`` greater
- or equal to 1) might break some tests and features as ``pd.show_versions()``
- as the version number cannot be computed anymore.
-
-Creating a feature branch
--------------------------
-
-Your local ``main`` branch should always reflect the current state of pandas repository.
-First ensure it's up-to-date with the main pandas repository.
-
-.. code-block:: shell
-
- git checkout main
- git pull upstream main --ff-only
-
-Then, create a feature branch for making your changes. For example
-
-.. code-block:: shell
-
- git checkout -b shiny-new-feature
-
-This changes your working branch from ``main`` to the ``shiny-new-feature`` branch. Keep any
-changes in this branch specific to one bug or feature so it is clear
-what the branch brings to pandas. You can have many feature branches
-and switch in between them using the ``git checkout`` command.
-
-When you want to update the feature branch with changes in main after
-you created the branch, check the section on
-:ref:`updating a PR `.
-
-.. _contributing.commit-code:
-
-Making code changes
--------------------
-
-Before modifying any code, ensure you follow the :ref:`contributing environment `
-guidelines to set up an appropriate development environment.
-
-Then once you have made code changes, you can see all the changes you've currently made by running.
-
-.. code-block:: shell
-
- git status
-
-For files you intended to modify or add, run.
-
-.. code-block:: shell
-
- git add path/to/file-to-be-added-or-changed.py
-
-Running ``git status`` again should display
-
-.. code-block:: shell
-
- On branch shiny-new-feature
-
- modified: /relative/path/to/file-to-be-added-or-changed.py
-
-
-Finally, commit your changes to your local repository with an explanatory commit
-message
-
-.. code-block:: shell
-
- git commit -m "your commit message goes here"
-
-.. _contributing.push-code:
-
-Pushing your changes
---------------------
-
-When you want your changes to appear publicly on your GitHub page, push your
-forked feature branch's commits
-
-.. code-block:: shell
-
- git push origin shiny-new-feature
-
-Here ``origin`` is the default name given to your remote repository on GitHub.
-You can see the remote repositories
-
-.. code-block:: shell
-
- git remote -v
-
-If you added the upstream repository as described above you will see something
-like
-
-.. code-block:: shell
-
- origin git@github.com:yourname/pandas.git (fetch)
- origin git@github.com:yourname/pandas.git (push)
- upstream git://github.com/pandas-dev/pandas.git (fetch)
- upstream git://github.com/pandas-dev/pandas.git (push)
-
-Now your code is on GitHub, but it is not yet a part of the pandas project. For that to
-happen, a pull request needs to be submitted on GitHub.
-
-Making a pull request
----------------------
-
-One you have finished your code changes, your code change will need to follow the
-:ref:`pandas contribution guidelines ` to be successfully accepted.
-
-If everything looks good, you are ready to make a pull request. A pull request is how
-code from your local repository becomes available to the GitHub community to review
-and merged into project to appear the in the next release. To submit a pull request:
-
-#. Navigate to your repository on GitHub
-#. Click on the ``Compare & pull request`` button
-#. You can then click on ``Commits`` and ``Files Changed`` to make sure everything looks
- okay one last time
-#. Write a descriptive title that includes prefixes. pandas uses a convention for title
- prefixes. Here are some common ones along with general guidelines for when to use them:
-
- * ENH: Enhancement, new functionality
- * BUG: Bug fix
- * DOC: Additions/updates to documentation
- * TST: Additions/updates to tests
- * BLD: Updates to the build process/scripts
- * PERF: Performance improvement
- * TYP: Type annotations
- * CLN: Code cleanup
-
-#. Write a description of your changes in the ``Preview Discussion`` tab
-#. Click ``Send Pull Request``.
-
-This request then goes to the repository maintainers, and they will review
-the code.
-
-.. _contributing.update-pr:
-
-Updating your pull request
---------------------------
-
-Based on the review you get on your pull request, you will probably need to make
-some changes to the code. You can follow the :ref:`code committing steps `
-again to address any feedback and update your pull request.
-
-It is also important that updates in the pandas ``main`` branch are reflected in your pull request.
-To update your feature branch with changes in the pandas ``main`` branch, run:
-
-.. code-block:: shell
-
- git checkout shiny-new-feature
- git fetch upstream
- git merge upstream/main
-
-If there are no conflicts (or they could be fixed automatically), a file with a
-default commit message will open, and you can simply save and quit this file.
-
-If there are merge conflicts, you need to solve those conflicts. See for
-example at https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
-for an explanation on how to do this.
-
-Once the conflicts are resolved, run:
-
-#. ``git add -u`` to stage any files you've updated;
-#. ``git commit`` to finish the merge.
-
-.. note::
-
- If you have uncommitted changes at the moment you want to update the branch with
- ``main``, you will need to ``stash`` them prior to updating (see the
- `stash docs `__).
- This will effectively store your changes and they can be reapplied after updating.
-
-After the feature branch has been update locally, you can now update your pull
-request by pushing to the branch on GitHub:
-
-.. code-block:: shell
-
- git push origin shiny-new-feature
-
-Any ``git push`` will automatically update your pull request with your branch's changes
-and restart the :ref:`Continuous Integration ` checks.
-
-.. _contributing.update-dev:
-
-Updating the development environment
-------------------------------------
-
-It is important to periodically update your local ``main`` branch with updates from the pandas ``main``
-branch and update your development environment to reflect any changes to the various packages that
-are used during development.
-
-If using :ref:`conda `, run:
-
-.. code-block:: shell
-
- git checkout main
- git fetch upstream
- git merge upstream/main
- conda activate pandas-dev
- conda env update -f environment.yml --prune
-
-If using :ref:`pip ` , do:
-
-.. code-block:: shell
-
- git checkout main
- git fetch upstream
- git merge upstream/main
- # activate the virtual environment based on your platform
- python -m pip install --upgrade -r requirements-dev.txt
-
-Tips for a successful pull request
-==================================
-
-If you have made it to the `Making a pull request`_ phase, one of the core contributors may
-take a look. Please note however that a handful of people are responsible for reviewing
-all of the contributions, which can often lead to bottlenecks.
-
-To improve the chances of your pull request being reviewed, you should:
-
-- **Reference an open issue** for non-trivial changes to clarify the PR's purpose
-- **Ensure you have appropriate tests**. These should be the first part of any PR
-- **Keep your pull requests as simple as possible**. Larger PRs take longer to review
-- **Ensure that CI is in a green state**. Reviewers may not even look otherwise
-- **Keep** `Updating your pull request`_, either by request or every few days
diff --git a/doc/source/development/contributing_codebase.rst b/doc/source/development/contributing_codebase.rst
deleted file mode 100644
index 73bc756de9302..0000000000000
--- a/doc/source/development/contributing_codebase.rst
+++ /dev/null
@@ -1,964 +0,0 @@
-.. _contributing_codebase:
-
-{{ header }}
-
-=============================
-Contributing to the code base
-=============================
-
-.. contents:: Table of Contents:
- :local:
-
-Code standards
---------------
-
-Writing good code is not just about what you write. It is also about *how* you
-write it. During :ref:`Continuous Integration ` testing, several
-tools will be run to check your code for stylistic errors.
-Generating any warnings will cause the test to fail.
-Thus, good style is a requirement for submitting code to pandas.
-
-There are a couple of tools in pandas to help contributors verify their changes
-before contributing to the project
-
-- ``./ci/code_checks.sh``: a script validates the doctests, formatting in docstrings,
- and imported modules. It is possible to run the checks independently by using the
- parameters ``docstrings``, ``code``, and ``doctests``
- (e.g. ``./ci/code_checks.sh doctests``);
-- ``pre-commit``, which we go into detail on in the next section.
-
-In addition, because a lot of people use our library, it is important that we
-do not make sudden changes to the code that could have the potential to break
-a lot of user code as a result, that is, we need it to be as *backwards compatible*
-as possible to avoid mass breakages.
-
-.. _contributing.pre-commit:
-
-Pre-commit
-----------
-
-Additionally, :ref:`Continuous Integration ` will run code formatting checks
-like ``ruff``,
-``isort``, and ``clang-format`` and more using `pre-commit hooks `_.
-Any warnings from these checks will cause the :ref:`Continuous Integration ` to fail; therefore,
-it is helpful to run the check yourself before submitting code. This
-can be done by installing ``pre-commit`` (which should already have happened if you followed the instructions
-in :ref:`Setting up your development environment `) and then running::
-
- pre-commit install
-
-from the root of the pandas repository. Now all of the styling checks will be
-run each time you commit changes without your needing to run each one manually.
-In addition, using ``pre-commit`` will also allow you to more easily
-remain up-to-date with our code checks as they change.
-
-Note that if needed, you can skip these checks with ``git commit --no-verify``.
-
-If you don't want to use ``pre-commit`` as part of your workflow, you can still use it
-to run its checks with one of the following::
-
- pre-commit run --files
- pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files
-
-without needing to have done ``pre-commit install`` beforehand.
-
-Finally, we also have some slow pre-commit checks, which don't run on each commit
-but which do run during continuous integration. You can trigger them manually with::
-
- pre-commit run --hook-stage manual --all-files
-
-.. note::
-
- You may want to periodically run ``pre-commit gc``, to clean up repos
- which are no longer used.
-
-.. note::
-
- If you have conflicting installations of ``virtualenv``, then you may get an
- error - see `here `_.
-
- Also, due to a `bug in virtualenv `_,
- you may run into issues if you're using conda. To solve this, you can downgrade
- ``virtualenv`` to version ``20.0.33``.
-
-.. note::
-
- If you have recently merged in main from the upstream branch, some of the
- dependencies used by ``pre-commit`` may have changed. Make sure to
- :ref:`update your development environment `.
-
-Optional dependencies
----------------------
-
-Optional dependencies (e.g. matplotlib) should be imported with the private helper
-``pandas.compat._optional.import_optional_dependency``. This ensures a
-consistent error message when the dependency is not met.
-
-All methods using an optional dependency should include a test asserting that an
-``ImportError`` is raised when the optional dependency is not found. This test
-should be skipped if the library is present.
-
-All optional dependencies should be documented in
-:ref:`install.optional_dependencies` and the minimum required version should be
-set in the ``pandas.compat._optional.VERSIONS`` dict.
-
-Backwards compatibility
------------------------
-
-Please try to maintain backward compatibility. pandas has lots of users with lots of
-existing code, so don't break it if at all possible. If you think breakage is required,
-clearly state why as part of the pull request. Also, be careful when changing method
-signatures and add deprecation warnings where needed. Also, add the deprecated sphinx
-directive to the deprecated functions or methods.
-
-If a function with the same arguments as the one being deprecated exist, you can use
-the ``pandas.util._decorators.deprecate``:
-
-.. code-block:: python
-
- from pandas.util._decorators import deprecate
-
- deprecate('old_func', 'new_func', '1.1.0')
-
-Otherwise, you need to do it manually:
-
-.. code-block:: python
-
- import warnings
- from pandas.util._exceptions import find_stack_level
-
-
- def old_func():
- """Summary of the function.
-
- .. deprecated:: 1.1.0
- Use new_func instead.
- """
- warnings.warn(
- 'Use new_func instead.',
- FutureWarning,
- stacklevel=find_stack_level(),
- )
- new_func()
-
-
- def new_func():
- pass
-
-You'll also need to
-
-1. Write a new test that asserts a warning is issued when calling with the deprecated argument
-2. Update all of pandas existing tests and code to use the new argument
-
-See :ref:`contributing.warnings` for more.
-
-.. _contributing.type_hints:
-
-Type hints
-----------
-
-pandas strongly encourages the use of :pep:`484` style type hints. New development should contain type hints and pull requests to annotate existing code are accepted as well!
-
-Style guidelines
-~~~~~~~~~~~~~~~~
-
-Type imports should follow the ``from typing import ...`` convention.
-Your code may be automatically re-written to use some modern constructs (e.g. using the built-in ``list`` instead of ``typing.List``)
-by the :ref:`pre-commit checks `.
-
-In some cases in the code base classes may define class variables that shadow builtins. This causes an issue as described in `Mypy 1775 `_. The defensive solution here is to create an unambiguous alias of the builtin and use that without your annotation. For example, if you come across a definition like
-
-.. code-block:: python
-
- class SomeClass1:
- str = None
-
-The appropriate way to annotate this would be as follows
-
-.. code-block:: python
-
- str_type = str
-
- class SomeClass2:
- str: str_type = None
-
-In some cases you may be tempted to use ``cast`` from the typing module when you know better than the analyzer. This occurs particularly when using custom inference functions. For example
-
-.. code-block:: python
-
- from typing import cast
-
- from pandas.core.dtypes.common import is_number
-
- def cannot_infer_bad(obj: Union[str, int, float]):
-
- if is_number(obj):
- ...
- else: # Reasonably only str objects would reach this but...
- obj = cast(str, obj) # Mypy complains without this!
- return obj.upper()
-
-The limitation here is that while a human can reasonably understand that ``is_number`` would catch the ``int`` and ``float`` types mypy cannot make that same inference just yet (see `mypy #5206 `_). While the above works, the use of ``cast`` is **strongly discouraged**. Where applicable a refactor of the code to appease static analysis is preferable
-
-.. code-block:: python
-
- def cannot_infer_good(obj: Union[str, int, float]):
-
- if isinstance(obj, str):
- return obj.upper()
- else:
- ...
-
-With custom types and inference this is not always possible so exceptions are made, but every effort should be exhausted to avoid ``cast`` before going down such paths.
-
-pandas-specific types
-~~~~~~~~~~~~~~~~~~~~~
-
-Commonly used types specific to pandas will appear in `pandas._typing `_ and you should use these where applicable. This module is private for now but ultimately this should be exposed to third party libraries who want to implement type checking against pandas.
-
-For example, quite a few functions in pandas accept a ``dtype`` argument. This can be expressed as a string like ``"object"``, a ``numpy.dtype`` like ``np.int64`` or even a pandas ``ExtensionDtype`` like ``pd.CategoricalDtype``. Rather than burden the user with having to constantly annotate all of those options, this can simply be imported and reused from the pandas._typing module
-
-.. code-block:: python
-
- from pandas._typing import Dtype
-
- def as_type(dtype: Dtype) -> ...:
- ...
-
-This module will ultimately house types for repeatedly used concepts like "path-like", "array-like", "numeric", etc... and can also hold aliases for commonly appearing parameters like ``axis``. Development of this module is active so be sure to refer to the source for the most up to date list of available types.
-
-Validating type hints
-~~~~~~~~~~~~~~~~~~~~~
-
-pandas uses `mypy `_ and `pyright `_ to statically analyze the code base and type hints. After making any change you can ensure your type hints are consistent by running
-
-.. code-block:: shell
-
- pre-commit run --hook-stage manual --all-files mypy
- pre-commit run --hook-stage manual --all-files pyright
- pre-commit run --hook-stage manual --all-files pyright_reportGeneralTypeIssues
- # the following might fail if the installed pandas version does not correspond to your local git version
- pre-commit run --hook-stage manual --all-files stubtest
-
-in your python environment.
-
-.. warning::
-
- * Please be aware that the above commands will use the current python environment. If your python packages are older/newer than those installed by the pandas CI, the above commands might fail. This is often the case when the ``mypy`` or ``numpy`` versions do not match. Please see :ref:`how to setup the python environment ` or select a `recently succeeded workflow `_, select the "Docstring validation, typing, and other manual pre-commit hooks" job, then click on "Set up Conda" and "Environment info" to see which versions the pandas CI installs.
-
-.. _contributing.ci:
-
-Testing type hints in code using pandas
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. warning::
-
- * pandas is not yet a py.typed library (:pep:`561`)!
- The primary purpose of locally declaring pandas as a py.typed library is to test and
- improve the pandas-builtin type annotations.
-
-Until pandas becomes a py.typed library, it is possible to easily experiment with the type
-annotations shipped with pandas by creating an empty file named "py.typed" in the pandas
-installation folder:
-
-.. code-block:: none
-
- python -c "import pandas; import pathlib; (pathlib.Path(pandas.__path__[0]) / 'py.typed').touch()"
-
-The existence of the py.typed file signals to type checkers that pandas is already a py.typed
-library. This makes type checkers aware of the type annotations shipped with pandas.
-
-Testing with continuous integration
------------------------------------
-
-The pandas test suite will run automatically on `GitHub Actions `__
-continuous integration services, once your pull request is submitted.
-However, if you wish to run the test suite on a branch prior to submitting the pull request,
-then the continuous integration services need to be hooked to your GitHub repository. Instructions are here
-for `GitHub Actions `__.
-
-A pull-request will be considered for merging when you have an all 'green' build. If any tests are failing,
-then you will get a red 'X', where you can click through to see the individual failed tests.
-This is an example of a green build.
-
-.. image:: ../_static/ci.png
-
-.. _contributing.tdd:
-
-
-Test-driven development
------------------------
-
-pandas is serious about testing and strongly encourages contributors to embrace
-`test-driven development (TDD) `_.
-This development process "relies on the repetition of a very short development cycle:
-first the developer writes an (initially failing) automated test case that defines a desired
-improvement or new function, then produces the minimum amount of code to pass that test."
-So, before actually writing any code, you should write your tests. Often the test can be
-taken from the original GitHub issue. However, it is always worth considering additional
-use cases and writing corresponding tests.
-
-We use `code coverage `_ to help understand
-the amount of code which is covered by a test. We recommend striving to ensure code
-you add or change within Pandas is covered by a test. Please see our
-`code coverage dashboard through Codecov `_
-for more information.
-
-Adding tests is one of the most common requests after code is pushed to pandas. Therefore,
-it is worth getting in the habit of writing tests ahead of time so this is never an issue.
-
-Writing tests
-~~~~~~~~~~~~~
-
-All tests should go into the ``tests`` subdirectory of the specific package.
-This folder contains many current examples of tests, and we suggest looking to these for
-inspiration.
-
-As a general tip, you can use the search functionality in your integrated development
-environment (IDE) or the git grep command in a terminal to find test files in which the method
-is called. If you are unsure of the best location to put your test, take your best guess,
-but note that reviewers may request that you move the test to a different location.
-
-To use git grep, you can run the following command in a terminal:
-
-``git grep "function_name("``
-
-This will search through all files in your repository for the text ``function_name(``.
-This can be a useful way to quickly locate the function in the
-codebase and determine the best location to add a test for it.
-
-Ideally, there should be one, and only one, obvious place for a test to reside.
-Until we reach that ideal, these are some rules of thumb for where a test should
-be located.
-
-1. Does your test depend only on code in ``pd._libs.tslibs``?
- This test likely belongs in one of:
-
- - tests.tslibs
-
- .. note::
-
- No file in ``tests.tslibs`` should import from any pandas modules
- outside of ``pd._libs.tslibs``
-
- - tests.scalar
- - tests.tseries.offsets
-
-2. Does your test depend only on code in ``pd._libs``?
- This test likely belongs in one of:
-
- - tests.libs
- - tests.groupby.test_libgroupby
-
-3. Is your test for an arithmetic or comparison method?
- This test likely belongs in one of:
-
- - tests.arithmetic
-
- .. note::
-
- These are intended for tests that can be shared to test the behavior
- of DataFrame/Series/Index/ExtensionArray using the ``box_with_array``
- fixture.
-
- - tests.frame.test_arithmetic
- - tests.series.test_arithmetic
-
-4. Is your test for a reduction method (min, max, sum, prod, ...)?
- This test likely belongs in one of:
-
- - tests.reductions
-
- .. note::
-
- These are intended for tests that can be shared to test the behavior
- of DataFrame/Series/Index/ExtensionArray.
-
- - tests.frame.test_reductions
- - tests.series.test_reductions
- - tests.test_nanops
-
-5. Is your test for an indexing method?
- This is the most difficult case for deciding where a test belongs, because
- there are many of these tests, and many of them test more than one method
- (e.g. both ``Series.__getitem__`` and ``Series.loc.__getitem__``)
-
- A) Is the test specifically testing an Index method (e.g. ``Index.get_loc``,
- ``Index.get_indexer``)?
- This test likely belongs in one of:
-
- - tests.indexes.test_indexing
- - tests.indexes.fooindex.test_indexing
-
- Within that files there should be a method-specific test class e.g.
- ``TestGetLoc``.
-
- In most cases, neither ``Series`` nor ``DataFrame`` objects should be
- needed in these tests.
-
- B) Is the test for a Series or DataFrame indexing method *other* than
- ``__getitem__`` or ``__setitem__``, e.g. ``xs``, ``where``, ``take``,
- ``mask``, ``lookup``, or ``insert``?
- This test likely belongs in one of:
-
- - tests.frame.indexing.test_methodname
- - tests.series.indexing.test_methodname
-
- C) Is the test for any of ``loc``, ``iloc``, ``at``, or ``iat``?
- This test likely belongs in one of:
-
- - tests.indexing.test_loc
- - tests.indexing.test_iloc
- - tests.indexing.test_at
- - tests.indexing.test_iat
-
- Within the appropriate file, test classes correspond to either types of
- indexers (e.g. ``TestLocBooleanMask``) or major use cases
- (e.g. ``TestLocSetitemWithExpansion``).
-
- See the note in section D) about tests that test multiple indexing methods.
-
- D) Is the test for ``Series.__getitem__``, ``Series.__setitem__``,
- ``DataFrame.__getitem__``, or ``DataFrame.__setitem__``?
- This test likely belongs in one of:
-
- - tests.series.test_getitem
- - tests.series.test_setitem
- - tests.frame.test_getitem
- - tests.frame.test_setitem
-
- If many cases such a test may test multiple similar methods, e.g.
-
- .. code-block:: python
-
- import pandas as pd
- import pandas._testing as tm
-
- def test_getitem_listlike_of_ints():
- ser = pd.Series(range(5))
-
- result = ser[[3, 4]]
- expected = pd.Series([2, 3])
- tm.assert_series_equal(result, expected)
-
- result = ser.loc[[3, 4]]
- tm.assert_series_equal(result, expected)
-
- In cases like this, the test location should be based on the *underlying*
- method being tested. Or in the case of a test for a bugfix, the location
- of the actual bug. So in this example, we know that ``Series.__getitem__``
- calls ``Series.loc.__getitem__``, so this is *really* a test for
- ``loc.__getitem__``. So this test belongs in ``tests.indexing.test_loc``.
-
-6. Is your test for a DataFrame or Series method?
-
- A) Is the method a plotting method?
- This test likely belongs in one of:
-
- - tests.plotting
-
- B) Is the method an IO method?
- This test likely belongs in one of:
-
- - tests.io
-
- .. note::
-
- This includes ``to_string`` but excludes ``__repr__``, which is
- tested in ``tests.frame.test_repr`` and ``tests.series.test_repr``.
- Other classes often have a ``test_formats`` file.
-
- C) Otherwise
- This test likely belongs in one of:
-
- - tests.series.methods.test_mymethod
- - tests.frame.methods.test_mymethod
-
- .. note::
-
- If a test can be shared between DataFrame/Series using the
- ``frame_or_series`` fixture, by convention it goes in the
- ``tests.frame`` file.
-
-7. Is your test for an Index method, not depending on Series/DataFrame?
- This test likely belongs in one of:
-
- - tests.indexes
-
-8) Is your test for one of the pandas-provided ExtensionArrays (``Categorical``,
- ``DatetimeArray``, ``TimedeltaArray``, ``PeriodArray``, ``IntervalArray``,
- ``NumpyExtensionArray``, ``FloatArray``, ``BoolArray``, ``StringArray``)?
- This test likely belongs in one of:
-
- - tests.arrays
-
-9) Is your test for *all* ExtensionArray subclasses (the "EA Interface")?
- This test likely belongs in one of:
-
- - tests.extension
-
-Using ``pytest``
-~~~~~~~~~~~~~~~~
-
-Test structure
-^^^^^^^^^^^^^^
-
-pandas existing test structure is *mostly* class-based, meaning that you will typically find tests wrapped in a class.
-
-.. code-block:: python
-
- class TestReallyCoolFeature:
- def test_cool_feature_aspect(self):
- pass
-
-We prefer a more *functional* style using the `pytest `__ framework, which offers a richer testing
-framework that will facilitate testing and developing. Thus, instead of writing test classes, we will write test functions like this:
-
-.. code-block:: python
-
- def test_really_cool_feature():
- pass
-
-Preferred ``pytest`` idioms
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Functional tests named ``def test_*`` and *only* take arguments that are either fixtures or parameters.
-* Use a bare ``assert`` for testing scalars and truth-testing
-* Use ``tm.assert_series_equal(result, expected)`` and ``tm.assert_frame_equal(result, expected)`` for comparing :class:`Series` and :class:`DataFrame` results respectively.
-* Use `@pytest.mark.parameterize `__ when testing multiple cases.
-* Use `pytest.mark.xfail `__ when a test case is expected to fail.
-* Use `pytest.mark.skip `__ when a test case is never expected to pass.
-* Use `pytest.param `__ when a test case needs a particular mark.
-* Use `@pytest.fixture `__ if multiple tests can share a setup object.
-
-.. warning::
-
- Do not use ``pytest.xfail`` (which is different than ``pytest.mark.xfail``) since it immediately stops the
- test and does not check if the test will fail. If this is the behavior you desire, use ``pytest.skip`` instead.
-
-If a test is known to fail but the manner in which it fails
-is not meant to be captured, use ``pytest.mark.xfail``. It is common to use this method for a test that
-exhibits buggy behavior or a non-implemented feature. If
-the failing test has flaky behavior, use the argument ``strict=False``. This
-will make it so pytest does not fail if the test happens to pass. Using ``strict=False`` is highly undesirable, please use it only as a last resort.
-
-Prefer the decorator ``@pytest.mark.xfail`` and the argument ``pytest.param``
-over usage within a test so that the test is appropriately marked during the
-collection phase of pytest. For xfailing a test that involves multiple
-parameters, a fixture, or a combination of these, it is only possible to
-xfail during the testing phase. To do so, use the ``request`` fixture:
-
-.. code-block:: python
-
- def test_xfail(request):
- mark = pytest.mark.xfail(raises=TypeError, reason="Indicate why here")
- request.applymarker(mark)
-
-xfail is not to be used for tests involving failure due to invalid user arguments.
-For these tests, we need to verify the correct exception type and error message
-is being raised, using ``pytest.raises`` instead.
-
-.. _contributing.warnings:
-
-Testing a warning
-^^^^^^^^^^^^^^^^^
-
-Use ``tm.assert_produces_warning`` as a context manager to check that a block of code raises a warning
-and specify the warning message using the ``match`` argument.
-
-.. code-block:: python
-
- with tm.assert_produces_warning(DeprecationWarning, match="the warning message"):
- pd.deprecated_function()
-
-If a warning should specifically not happen in a block of code, pass ``False`` into the context manager.
-
-.. code-block:: python
-
- with tm.assert_produces_warning(False):
- pd.no_warning_function()
-
-If you have a test that would emit a warning, but you aren't actually testing the
-warning itself (say because it's going to be removed in the future, or because we're
-matching a 3rd-party library's behavior), then use ``pytest.mark.filterwarnings`` to
-ignore the error.
-
-.. code-block:: python
-
- @pytest.mark.filterwarnings("ignore:msg:category")
- def test_thing(self):
- pass
-
-Testing an exception
-^^^^^^^^^^^^^^^^^^^^
-
-Use `pytest.raises `_ as a context manager
-with the specific exception subclass (i.e. never use :py:class:`Exception`) and the exception message in ``match``.
-
-.. code-block:: python
-
- with pytest.raises(ValueError, match="an error"):
- raise ValueError("an error")
-
-Testing involving files
-^^^^^^^^^^^^^^^^^^^^^^^
-
-The ``temp_file`` pytest fixture creates a temporary file :py:class:`Pathlib` object for testing:
-
-.. code-block:: python
-
- def test_something(temp_file):
- pd.DataFrame([1]).to_csv(str(temp_file))
-
-Please reference `pytest's documentation `_
-for the file retention policy.
-
-Testing involving network connectivity
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A unit test should not access a public data set over the internet due to flakiness of network connections and
-lack of ownership of the server that is being connected to. To mock this interaction, use the ``httpserver`` fixture from the
-`pytest-localserver plugin. `_ with synthetic data.
-
-.. code-block:: python
-
- @pytest.mark.network
- @pytest.mark.single_cpu
- def test_network(httpserver):
- httpserver.serve_content(content="content")
- result = pd.read_html(httpserver.url)
-
-Example
-^^^^^^^
-
-Here is an example of a self-contained set of tests in a file ``pandas/tests/test_cool_feature.py``
-that illustrate multiple features that we like to use. Please remember to add the GitHub Issue Number
-as a comment to a new test.
-
-.. code-block:: python
-
- import pytest
- import numpy as np
- import pandas as pd
-
-
- @pytest.mark.parametrize('dtype', ['int8', 'int16', 'int32', 'int64'])
- def test_dtypes(dtype):
- assert str(np.dtype(dtype)) == dtype
-
-
- @pytest.mark.parametrize(
- 'dtype', ['float32', pytest.param('int16', marks=pytest.mark.skip),
- pytest.param('int32', marks=pytest.mark.xfail(
- reason='to show how it works'))])
- def test_mark(dtype):
- assert str(np.dtype(dtype)) == 'float32'
-
-
- @pytest.fixture
- def series():
- return pd.Series([1, 2, 3])
-
-
- @pytest.fixture(params=['int8', 'int16', 'int32', 'int64'])
- def dtype(request):
- return request.param
-
-
- def test_series(series, dtype):
- # GH
- result = series.astype(dtype)
- assert result.dtype == dtype
-
- expected = pd.Series([1, 2, 3], dtype=dtype)
- tm.assert_series_equal(result, expected)
-
-
-A test run of this yields
-
-.. code-block:: shell
-
- ((pandas) bash-3.2$ pytest test_cool_feature.py -v
- =========================== test session starts ===========================
- platform darwin -- Python 3.6.2, pytest-3.6.0, py-1.4.31, pluggy-0.4.0
- collected 11 items
-
- tester.py::test_dtypes[int8] PASSED
- tester.py::test_dtypes[int16] PASSED
- tester.py::test_dtypes[int32] PASSED
- tester.py::test_dtypes[int64] PASSED
- tester.py::test_mark[float32] PASSED
- tester.py::test_mark[int16] SKIPPED
- tester.py::test_mark[int32] xfail
- tester.py::test_series[int8] PASSED
- tester.py::test_series[int16] PASSED
- tester.py::test_series[int32] PASSED
- tester.py::test_series[int64] PASSED
-
-Tests that we have ``parametrized`` are now accessible via the test name, for example we could run these with ``-k int8`` to sub-select *only* those tests which match ``int8``.
-
-
-.. code-block:: shell
-
- ((pandas) bash-3.2$ pytest test_cool_feature.py -v -k int8
- =========================== test session starts ===========================
- platform darwin -- Python 3.6.2, pytest-3.6.0, py-1.4.31, pluggy-0.4.0
- collected 11 items
-
- test_cool_feature.py::test_dtypes[int8] PASSED
- test_cool_feature.py::test_series[int8] PASSED
-
-
-.. _using-hypothesis:
-
-Using ``hypothesis``
-~~~~~~~~~~~~~~~~~~~~
-
-Hypothesis is a library for property-based testing. Instead of explicitly
-parametrizing a test, you can describe *all* valid inputs and let Hypothesis
-try to find a failing input. Even better, no matter how many random examples
-it tries, Hypothesis always reports a single minimal counterexample to your
-assertions - often an example that you would never have thought to test.
-
-See `Getting Started with Hypothesis `_
-for more of an introduction, then `refer to the Hypothesis documentation
-for details `_.
-
-.. code-block:: python
-
- import json
- from hypothesis import given, strategies as st
-
- any_json_value = st.deferred(lambda: st.one_of(
- st.none(), st.booleans(), st.floats(allow_nan=False), st.text(),
- st.lists(any_json_value), st.dictionaries(st.text(), any_json_value)
- ))
-
-
- @given(value=any_json_value)
- def test_json_roundtrip(value):
- result = json.loads(json.dumps(value))
- assert value == result
-
-This test shows off several useful features of Hypothesis, as well as
-demonstrating a good use-case: checking properties that should hold over
-a large or complicated domain of inputs.
-
-To keep the pandas test suite running quickly, parametrized tests are
-preferred if the inputs or logic are simple, with Hypothesis tests reserved
-for cases with complex logic or where there are too many combinations of
-options or subtle interactions to test (or think of!) all of them.
-
-.. _contributing.running_tests:
-
-Running the test suite
-----------------------
-
-The tests can then be run directly inside your Git clone (without having to
-install pandas) by typing::
-
- pytest pandas
-
-.. note::
-
- If a handful of tests don't pass, it may not be an issue with your pandas installation.
- Some tests (e.g. some SQLAlchemy ones) require additional setup, others might start
- failing because a non-pinned library released a new version, and others might be flaky
- if run in parallel. As long as you can import pandas from your locally built version,
- your installation is probably fine and you can start contributing!
-
-Often it is worth running only a subset of tests first around your changes before running the
-entire suite.
-
-The easiest way to do this is with::
-
- pytest pandas/path/to/test.py -k regex_matching_test_name
-
-Or with one of the following constructs::
-
- pytest pandas/tests/[test-module].py
- pytest pandas/tests/[test-module].py::[TestClass]
- pytest pandas/tests/[test-module].py::[TestClass]::[test_method]
-
-Using `pytest-xdist `_, which is
-included in our 'pandas-dev' environment, one can speed up local testing on
-multicore machines. The ``-n`` number flag then can be specified when running
-pytest to parallelize a test run across the number of specified cores or auto to
-utilize all the available cores on your machine.
-
-.. code-block:: bash
-
- # Utilize 4 cores
- pytest -n 4 pandas
-
- # Utilizes all available cores
- pytest -n auto pandas
-
-If you'd like to speed things along further a more advanced use of this
-command would look like this
-
-.. code-block:: bash
-
- pytest pandas -n 4 -m "not slow and not network and not db and not single_cpu" -r sxX
-
-In addition to the multithreaded performance increase this improves test
-speed by skipping some tests using the ``-m`` mark flag:
-
-- slow: any test taking long (think seconds rather than milliseconds)
-- network: tests requiring network connectivity
-- db: tests requiring a database (mysql or postgres)
-- single_cpu: tests that should run on a single cpu only
-
-You might want to enable the following option if it's relevant for you:
-
-- arm_slow: any test taking long on arm64 architecture
-
-These markers are defined `in this toml file `_
-, under ``[tool.pytest.ini_options]`` in a list called ``markers``, in case
-you want to check if new ones have been created which are of interest to you.
-
-The ``-r`` report flag will display a short summary info (see `pytest
-documentation `_)
-. Here we are displaying the number of:
-
-- s: skipped tests
-- x: xfailed tests
-- X: xpassed tests
-
-The summary is optional and can be removed if you don't need the added
-information. Using the parallelization option can significantly reduce the
-time it takes to locally run tests before submitting a pull request.
-
-If you require assistance with the results,
-which has happened in the past, please set a seed before running the command
-and opening a bug report, that way we can reproduce it. Here's an example
-for setting a seed on windows
-
-.. code-block:: bash
-
- set PYTHONHASHSEED=314159265
- pytest pandas -n 4 -m "not slow and not network and not db and not single_cpu" -r sxX
-
-On Unix use
-
-.. code-block:: bash
-
- export PYTHONHASHSEED=314159265
- pytest pandas -n 4 -m "not slow and not network and not db and not single_cpu" -r sxX
-
-For more, see the `pytest `_ documentation.
-
-Furthermore one can run
-
-.. code-block:: python
-
- pd.test()
-
-with an imported pandas to run tests similarly.
-
-Running the performance test suite
-----------------------------------
-
-Performance matters and it is worth considering whether your code has introduced
-performance regressions. pandas is in the process of migrating to
-`asv benchmarks `__
-to enable easy monitoring of the performance of critical pandas operations.
-These benchmarks are all found in the ``pandas/asv_bench`` directory, and the
-test results can be found `here `__.
-
-To use all features of asv, you will need either ``conda`` or
-``virtualenv``. For more details please check the `asv installation
-webpage `_.
-
-To install asv::
-
- pip install git+https://github.com/airspeed-velocity/asv
-
-If you need to run a benchmark, change your directory to ``asv_bench/`` and run::
-
- asv continuous -f 1.1 upstream/main HEAD
-
-You can replace ``HEAD`` with the name of the branch you are working on,
-and report benchmarks that changed by more than 10%.
-The command uses ``conda`` by default for creating the benchmark
-environments. If you want to use virtualenv instead, write::
-
- asv continuous -f 1.1 -E virtualenv upstream/main HEAD
-
-The ``-E virtualenv`` option should be added to all ``asv`` commands
-that run benchmarks. The default value is defined in ``asv.conf.json``.
-
-Running the full benchmark suite can be an all-day process, depending on your
-hardware and its resource utilization. However, usually it is sufficient to paste
-only a subset of the results into the pull request to show that the committed changes
-do not cause unexpected performance regressions. You can run specific benchmarks
-using the ``-b`` flag, which takes a regular expression. For example, this will
-only run benchmarks from a ``pandas/asv_bench/benchmarks/groupby.py`` file::
-
- asv continuous -f 1.1 upstream/main HEAD -b ^groupby
-
-If you want to only run a specific group of benchmarks from a file, you can do it
-using ``.`` as a separator. For example::
-
- asv continuous -f 1.1 upstream/main HEAD -b groupby.GroupByMethods
-
-will only run the ``GroupByMethods`` benchmark defined in ``groupby.py``.
-
-You can also run the benchmark suite using the version of ``pandas``
-already installed in your current Python environment. This can be
-useful if you do not have virtualenv or conda, or are using the
-``setup.py develop`` approach discussed above; for the in-place build
-you need to set ``PYTHONPATH``, e.g.
-``PYTHONPATH="$PWD/.." asv [remaining arguments]``.
-You can run benchmarks using an existing Python
-environment by::
-
- asv run -e -E existing
-
-or, to use a specific Python interpreter,::
-
- asv run -e -E existing:python3.6
-
-This will display stderr from the benchmarks, and use your local
-``python`` that comes from your ``$PATH``.
-
-Information on how to write a benchmark and how to use asv can be found in the
-`asv documentation `_.
-
-Documenting your code
----------------------
-
-Changes should be reflected in the release notes located in ``doc/source/whatsnew/vx.y.z.rst``.
-This file contains an ongoing change log for each release. Add an entry to this file to
-document your fix, enhancement or (unavoidable) breaking change. Make sure to include the
-GitHub issue number when adding your entry (using ``:issue:`1234``` where ``1234`` is the
-issue/pull request number). Your entry should be written using full sentences and proper
-grammar.
-
-When mentioning parts of the API, use a Sphinx ``:func:``, ``:meth:``, or ``:class:``
-directive as appropriate. Not all public API functions and methods have a
-documentation page; ideally links would only be added if they resolve. You can
-usually find similar examples by checking the release notes for one of the previous
-versions.
-
-If your code is a bugfix, add your entry to the relevant bugfix section. Avoid
-adding to the ``Other`` section; only in rare cases should entries go there.
-Being as concise as possible, the description of the bug should include how the
-user may encounter it and an indication of the bug itself, e.g.
-"produces incorrect results" or "incorrectly raises". It may be necessary to also
-indicate the new behavior.
-
-If your code is an enhancement, it is most likely necessary to add usage
-examples to the existing documentation. This can be done following the section
-regarding :ref:`documentation `.
-Further, to let users know when this feature was added, the ``versionadded``
-directive is used. The sphinx syntax for that is:
-
-.. code-block:: rst
-
- .. versionadded:: 2.1.0
-
-This will put the text *New in version 2.1.0* wherever you put the sphinx
-directive. This should also be put in the docstring when adding a new function
-or method (`example `__)
-or a new keyword argument (`example `__).
diff --git a/doc/source/development/contributing_docstring.rst b/doc/source/development/contributing_docstring.rst
deleted file mode 100644
index 59d7957275e15..0000000000000
--- a/doc/source/development/contributing_docstring.rst
+++ /dev/null
@@ -1,999 +0,0 @@
-.. _docstring:
-
-{{ header }}
-
-======================
-pandas docstring guide
-======================
-
-About docstrings and standards
-------------------------------
-
-A Python docstring is a string used to document a Python module, class,
-function or method, so programmers can understand what it does without having
-to read the details of the implementation.
-
-Also, it is a common practice to generate online (html) documentation
-automatically from docstrings. `Sphinx `_ serves
-this purpose.
-
-The next example gives an idea of what a docstring looks like:
-
-.. code-block:: python
-
- def add(num1, num2):
- """
- Add up two integer numbers.
-
- This function simply wraps the ``+`` operator, and does not
- do anything interesting, except for illustrating what
- the docstring of a very simple function looks like.
-
- Parameters
- ----------
- num1 : int
- First number to add.
- num2 : int
- Second number to add.
-
- Returns
- -------
- int
- The sum of ``num1`` and ``num2``.
-
- See Also
- --------
- subtract : Subtract one integer from another.
-
- Examples
- --------
- >>> add(2, 2)
- 4
- >>> add(25, 0)
- 25
- >>> add(10, -10)
- 0
- """
- return num1 + num2
-
-Some standards regarding docstrings exist, which make them easier to read, and allow them
-be easily exported to other formats such as html or pdf.
-
-The first conventions every Python docstring should follow are defined in
-`PEP-257 `_.
-
-As PEP-257 is quite broad, other more specific standards also exist. In the
-case of pandas, the NumPy docstring convention is followed. These conventions are
-explained in this document:
-
-* `numpydoc docstring guide `_
-
-numpydoc is a Sphinx extension to support the NumPy docstring convention.
-
-The standard uses reStructuredText (reST). reStructuredText is a markup
-language that allows encoding styles in plain text files. Documentation
-about reStructuredText can be found in:
-
-* `Sphinx reStructuredText primer `_
-* `Quick reStructuredText reference `_
-* `Full reStructuredText specification `_
-
-pandas has some helpers for sharing docstrings between related classes, see
-:ref:`docstring.sharing`.
-
-The rest of this document will summarize all the above guidelines, and will
-provide additional conventions specific to the pandas project.
-
-.. _docstring.tutorial:
-
-Writing a docstring
--------------------
-
-.. _docstring.general:
-
-General rules
-~~~~~~~~~~~~~
-
-Docstrings must be defined with three double-quotes. No blank lines should be
-left before or after the docstring. The text starts in the next line after the
-opening quotes. The closing quotes have their own line
-(meaning that they are not at the end of the last sentence).
-
-On rare occasions reST styles like bold text or italics will be used in
-docstrings, but is it common to have inline code, which is presented between
-backticks. The following are considered inline code:
-
-* The name of a parameter
-* Python code, a module, function, built-in, type, literal... (e.g. ``os``,
- ``list``, ``numpy.abs``, ``datetime.date``, ``True``)
-* A pandas class (in the form ``:class:`pandas.Series```)
-* A pandas method (in the form ``:meth:`pandas.Series.sum```)
-* A pandas function (in the form ``:func:`pandas.to_datetime```)
-
-.. note::
- To display only the last component of the linked class, method or
- function, prefix it with ``~``. For example, ``:class:`~pandas.Series```
- will link to ``pandas.Series`` but only display the last part, ``Series``
- as the link text. See `Sphinx cross-referencing syntax
- `_
- for details.
-
-**Good:**
-
-.. code-block:: python
-
- def add_values(arr):
- """
- Add the values in ``arr``.
-
- This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
-
- Some sections are omitted here for simplicity.
- """
- return sum(arr)
-
-**Bad:**
-
-.. code-block:: python
-
- def func():
-
- """Some function.
-
- With several mistakes in the docstring.
-
- It has a blank line after the signature ``def func():``.
-
- The text 'Some function' should go in the line after the
- opening quotes of the docstring, not in the same line.
-
- There is a blank line between the docstring and the first line
- of code ``foo = 1``.
-
- The closing quotes should be in the next line, not in this one."""
-
- foo = 1
- bar = 2
- return foo + bar
-
-.. _docstring.short_summary:
-
-Section 1: short summary
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The short summary is a single sentence that expresses what the function does in
-a concise way.
-
-The short summary must start with a capital letter, end with a dot, and fit in
-a single line. It needs to express what the object does without providing
-details. For functions and methods, the short summary must start with an
-infinitive verb.
-
-**Good:**
-
-.. code-block:: python
-
- def astype(dtype):
- """
- Cast Series type.
-
- This section will provide further details.
- """
- pass
-
-**Bad:**
-
-.. code-block:: python
-
- def astype(dtype):
- """
- Casts Series type.
-
- Verb in third-person of the present simple, should be infinitive.
- """
- pass
-
-.. code-block:: python
-
- def astype(dtype):
- """
- Method to cast Series type.
-
- Does not start with verb.
- """
- pass
-
-.. code-block:: python
-
- def astype(dtype):
- """
- Cast Series type
-
- Missing dot at the end.
- """
- pass
-
-.. code-block:: python
-
- def astype(dtype):
- """
- Cast Series type from its current type to the new type defined in
- the parameter dtype.
-
- Summary is too verbose and doesn't fit in a single line.
- """
- pass
-
-.. _docstring.extended_summary:
-
-Section 2: extended summary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The extended summary provides details on what the function does. It should not
-go into the details of the parameters, or discuss implementation notes, which
-go in other sections.
-
-A blank line is left between the short summary and the extended summary.
-Every paragraph in the extended summary ends with a dot.
-
-The extended summary should provide details on why the function is useful and
-their use cases, if it is not too generic.
-
-.. code-block:: python
-
- def unstack():
- """
- Pivot a row index to columns.
-
- When using a MultiIndex, a level can be pivoted so each value in
- the index becomes a column. This is especially useful when a subindex
- is repeated for the main index, and data is easier to visualize as a
- pivot table.
-
- The index level will be automatically removed from the index when added
- as columns.
- """
- pass
-
-.. _docstring.parameters:
-
-Section 3: parameters
-~~~~~~~~~~~~~~~~~~~~~
-
-The details of the parameters will be added in this section. This section has
-the title "Parameters", followed by a line with a hyphen under each letter of
-the word "Parameters". A blank line is left before the section title, but not
-after, and not between the line with the word "Parameters" and the one with
-the hyphens.
-
-After the title, each parameter in the signature must be documented, including
-``*args`` and ``**kwargs``, but not ``self``.
-
-The parameters are defined by their name, followed by a space, a colon, another
-space, and the type (or types). Note that the space between the name and the
-colon is important. Types are not defined for ``*args`` and ``**kwargs``, but must
-be defined for all other parameters. After the parameter definition, it is
-required to have a line with the parameter description, which is indented, and
-can have multiple lines. The description must start with a capital letter, and
-finish with a dot.
-
-For keyword arguments with a default value, the default will be listed after a
-comma at the end of the type. The exact form of the type in this case will be
-"int, default 0". In some cases it may be useful to explain what the default
-argument means, which can be added after a comma "int, default -1, meaning all
-cpus".
-
-In cases where the default value is ``None``, meaning that the value will not be
-used. Instead of ``"str, default None"``, it is preferred to write ``"str, optional"``.
-When ``None`` is a value being used, we will keep the form "str, default None".
-For example, in ``df.to_csv(compression=None)``, ``None`` is not a value being used,
-but means that compression is optional, and no compression is being used if not
-provided. In this case we will use ``"str, optional"``. Only in cases like
-``func(value=None)`` and ``None`` is being used in the same way as ``0`` or ``foo``
-would be used, then we will specify "str, int or None, default None".
-
-**Good:**
-
-.. code-block:: python
-
- class Series:
- def plot(self, kind, color='blue', **kwargs):
- """
- Generate a plot.
-
- Render the data in the Series as a matplotlib plot of the
- specified kind.
-
- Parameters
- ----------
- kind : str
- Kind of matplotlib plot.
- color : str, default 'blue'
- Color name or rgb code.
- **kwargs
- These parameters will be passed to the matplotlib plotting
- function.
- """
- pass
-
-**Bad:**
-
-.. code-block:: python
-
- class Series:
- def plot(self, kind, **kwargs):
- """
- Generate a plot.
-
- Render the data in the Series as a matplotlib plot of the
- specified kind.
-
- Note the blank line between the parameters title and the first
- parameter. Also, note that after the name of the parameter ``kind``
- and before the colon, a space is missing.
-
- Also, note that the parameter descriptions do not start with a
- capital letter, and do not finish with a dot.
-
- Finally, the ``**kwargs`` parameter is missing.
-
- Parameters
- ----------
-
- kind: str
- kind of matplotlib plot
- """
- pass
-
-.. _docstring.parameter_types:
-
-Parameter types
-^^^^^^^^^^^^^^^
-
-When specifying the parameter types, Python built-in data types can be used
-directly (the Python type is preferred to the more verbose string, integer,
-boolean, etc):
-
-* int
-* float
-* str
-* bool
-
-For complex types, define the subtypes. For ``dict`` and ``tuple``, as more than
-one type is present, we use the brackets to help read the type (curly brackets
-for ``dict`` and normal brackets for ``tuple``):
-
-* list of int
-* dict of {str : int}
-* tuple of (str, int, int)
-* tuple of (str,)
-* set of str
-
-In case where there are just a set of values allowed, list them in curly
-brackets and separated by commas (followed by a space). If the values are
-ordinal and they have an order, list them in this order. Otherwise, list
-the default value first, if there is one:
-
-* {0, 10, 25}
-* {'simple', 'advanced'}
-* {'low', 'medium', 'high'}
-* {'cat', 'dog', 'bird'}
-
-If the type is defined in a Python module, the module must be specified:
-
-* datetime.date
-* datetime.datetime
-* decimal.Decimal
-
-If the type is in a package, the module must be also specified:
-
-* numpy.ndarray
-* scipy.sparse.coo_matrix
-
-If the type is a pandas type, also specify pandas except for Series and
-DataFrame:
-
-* Series
-* DataFrame
-* pandas.Index
-* pandas.Categorical
-* pandas.arrays.SparseArray
-
-If the exact type is not relevant, but must be compatible with a NumPy
-array, array-like can be specified. If Any type that can be iterated is
-accepted, iterable can be used:
-
-* array-like
-* iterable
-
-If more than one type is accepted, separate them by commas, except the
-last two types, that need to be separated by the word 'or':
-
-* int or float
-* float, decimal.Decimal or None
-* str or list of str
-
-If ``None`` is one of the accepted values, it always needs to be the last in
-the list.
-
-For axis, the convention is to use something like:
-
-* axis : {0 or 'index', 1 or 'columns', None}, default None
-
-.. _docstring.returns:
-
-Section 4: returns or yields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the method returns a value, it will be documented in this section. Also
-if the method yields its output.
-
-The title of the section will be defined in the same way as the "Parameters".
-With the names "Returns" or "Yields" followed by a line with as many hyphens
-as the letters in the preceding word.
-
-The documentation of the return is also similar to the parameters. But in this
-case, no name will be provided, unless the method returns or yields more than
-one value (a tuple of values).
-
-The types for "Returns" and "Yields" are the same as the ones for the
-"Parameters". Also, the description must finish with a dot.
-
-For example, with a single value:
-
-.. code-block:: python
-
- def sample():
- """
- Generate and return a random number.
-
- The value is sampled from a continuous uniform distribution between
- 0 and 1.
-
- Returns
- -------
- float
- Random number generated.
- """
- return np.random.random()
-
-With more than one value:
-
-.. code-block:: python
-
- import string
-
- def random_letters():
- """
- Generate and return a sequence of random letters.
-
- The length of the returned string is also random, and is also
- returned.
-
- Returns
- -------
- length : int
- Length of the returned string.
- letters : str
- String of random letters.
- """
- length = np.random.randint(1, 10)
- letters = ''.join(np.random.choice(string.ascii_lowercase)
- for i in range(length))
- return length, letters
-
-If the method yields its value:
-
-.. code-block:: python
-
- def sample_values():
- """
- Generate an infinite sequence of random numbers.
-
- The values are sampled from a continuous uniform distribution between
- 0 and 1.
-
- Yields
- ------
- float
- Random number generated.
- """
- while True:
- yield np.random.random()
-
-.. _docstring.see_also:
-
-Section 5: see also
-~~~~~~~~~~~~~~~~~~~
-
-This section is used to let users know about pandas functionality
-related to the one being documented. In rare cases, if no related methods
-or functions can be found at all, this section can be skipped.
-
-An obvious example would be the ``head()`` and ``tail()`` methods. As ``tail()`` does
-the equivalent as ``head()`` but at the end of the ``Series`` or ``DataFrame``
-instead of at the beginning, it is good to let the users know about it.
-
-To give an intuition on what can be considered related, here there are some
-examples:
-
-* ``loc`` and ``iloc``, as they do the same, but in one case providing indices
- and in the other positions
-* ``max`` and ``min``, as they do the opposite
-* ``iterrows``, ``itertuples`` and ``items``, as it is easy that a user
- looking for the method to iterate over columns ends up in the method to
- iterate over rows, and vice-versa
-* ``fillna`` and ``dropna``, as both methods are used to handle missing values
-* ``read_csv`` and ``to_csv``, as they are complementary
-* ``merge`` and ``join``, as one is a generalization of the other
-* ``astype`` and ``pandas.to_datetime``, as users may be reading the
- documentation of ``astype`` to know how to cast as a date, and the way to do
- it is with ``pandas.to_datetime``
-* ``where`` is related to ``numpy.where``, as its functionality is based on it
-
-When deciding what is related, you should mainly use your common sense and
-think about what can be useful for the users reading the documentation,
-especially the less experienced ones.
-
-When relating to other libraries (mainly ``numpy``), use the name of the module
-first (not an alias like ``np``). If the function is in a module which is not
-the main one, like ``scipy.sparse``, list the full module (e.g.
-``scipy.sparse.coo_matrix``).
-
-This section has a header, "See Also" (note the capital
-S and A), followed by the line with hyphens and preceded by a blank line.
-
-After the header, we will add a line for each related method or function,
-followed by a space, a colon, another space, and a short description that
-illustrates what this method or function does, why is it relevant in this
-context, and what the key differences are between the documented function and
-the one being referenced. The description must also end with a dot.
-
-Note that in "Returns" and "Yields", the description is located on the line
-after the type. In this section, however, it is located on the same
-line, with a colon in between. If the description does not fit on the same
-line, it can continue onto other lines which must be further indented.
-
-For example:
-
-.. code-block:: python
-
- class Series:
- def head(self):
- """
- Return the first 5 elements of the Series.
-
- This function is mainly useful to preview the values of the
- Series without displaying the whole of it.
-
- Returns
- -------
- Series
- Subset of the original series with the 5 first values.
-
- See Also
- --------
- Series.tail : Return the last 5 elements of the Series.
- Series.iloc : Return a slice of the elements in the Series,
- which can also be used to return the first or last n.
- """
- return self.iloc[:5]
-
-.. _docstring.notes:
-
-Section 6: notes
-~~~~~~~~~~~~~~~~
-
-This is an optional section used for notes about the implementation of the
-algorithm, or to document technical aspects of the function behavior.
-
-Feel free to skip it, unless you are familiar with the implementation of the
-algorithm, or you discover some counter-intuitive behavior while writing the
-examples for the function.
-
-This section follows the same format as the extended summary section.
-
-.. _docstring.examples:
-
-Section 7: examples
-~~~~~~~~~~~~~~~~~~~
-
-This is one of the most important sections of a docstring, despite being
-placed in the last position, as often people understand concepts better
-by example than through accurate explanations.
-
-Examples in docstrings, besides illustrating the usage of the function or
-method, must be valid Python code, that returns the given output in a
-deterministic way, and that can be copied and run by users.
-
-Examples are presented as a session in the Python terminal. ``>>>`` is used to
-present code. ``...`` is used for code continuing from the previous line.
-Output is presented immediately after the last line of code generating the
-output (no blank lines in between). Comments describing the examples can
-be added with blank lines before and after them.
-
-The way to present examples is as follows:
-
-1. Import required libraries (except ``numpy`` and ``pandas``)
-
-2. Create the data required for the example
-
-3. Show a very basic example that gives an idea of the most common use case
-
-4. Add examples with explanations that illustrate how the parameters can be
- used for extended functionality
-
-A simple example could be:
-
-.. code-block:: python
-
- class Series:
-
- def head(self, n=5):
- """
- Return the first elements of the Series.
-
- This function is mainly useful to preview the values of the
- Series without displaying all of it.
-
- Parameters
- ----------
- n : int
- Number of values to return.
-
- Return
- ------
- pandas.Series
- Subset of the original series with the n first values.
-
- See Also
- --------
- tail : Return the last n elements of the Series.
-
- Examples
- --------
- >>> ser = pd.Series(['Ant', 'Bear', 'Cow', 'Dog', 'Falcon',
- ... 'Lion', 'Monkey', 'Rabbit', 'Zebra'])
- >>> ser.head()
- 0 Ant
- 1 Bear
- 2 Cow
- 3 Dog
- 4 Falcon
- dtype: object
-
- With the ``n`` parameter, we can change the number of returned rows:
-
- >>> ser.head(n=3)
- 0 Ant
- 1 Bear
- 2 Cow
- dtype: object
- """
- return self.iloc[:n]
-
-The examples should be as concise as possible. In cases where the complexity of
-the function requires long examples, is recommended to use blocks with headers
-in bold. Use double star ``**`` to make a text bold, like in ``**this example**``.
-
-.. _docstring.example_conventions:
-
-Conventions for the examples
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Code in examples is assumed to always start with these two lines which are not
-shown:
-
-.. code-block:: python
-
- import numpy as np
- import pandas as pd
-
-Any other module used in the examples must be explicitly imported, one per line (as
-recommended in :pep:`8#imports`)
-and avoiding aliases. Avoid excessive imports, but if needed, imports from
-the standard library go first, followed by third-party libraries (like
-matplotlib).
-
-When illustrating examples with a single ``Series`` use the name ``ser``, and if
-illustrating with a single ``DataFrame`` use the name ``df``. For indices,
-``idx`` is the preferred name. If a set of homogeneous ``Series`` or
-``DataFrame`` is used, name them ``ser1``, ``ser2``, ``ser3``... or ``df1``,
-``df2``, ``df3``... If the data is not homogeneous, and more than one structure
-is needed, name them with something meaningful, for example ``df_main`` and
-``df_to_join``.
-
-Data used in the example should be as compact as possible. The number of rows
-is recommended to be around 4, but make it a number that makes sense for the
-specific example. For example in the ``head`` method, it requires to be higher
-than 5, to show the example with the default values. If doing the ``mean``, we
-could use something like ``[1, 2, 3]``, so it is easy to see that the value
-returned is the mean.
-
-For more complex examples (grouping for example), avoid using data without
-interpretation, like a matrix of random numbers with columns A, B, C, D...
-And instead use a meaningful example, which makes it easier to understand the
-concept. Unless required by the example, use names of animals, to keep examples
-consistent. And numerical properties of them.
-
-When calling the method, keywords arguments ``head(n=3)`` are preferred to
-positional arguments ``head(3)``.
-
-**Good:**
-
-.. code-block:: python
-
- class Series:
-
- def mean(self):
- """
- Compute the mean of the input.
-
- Examples
- --------
- >>> ser = pd.Series([1, 2, 3])
- >>> ser.mean()
- 2
- """
- pass
-
-
- def fillna(self, value):
- """
- Replace missing values by ``value``.
-
- Examples
- --------
- >>> ser = pd.Series([1, np.nan, 3])
- >>> ser.fillna(0)
- [1, 0, 3]
- """
- pass
-
- def groupby_mean(self):
- """
- Group by index and return mean.
-
- Examples
- --------
- >>> ser = pd.Series([380., 370., 24., 26],
- ... name='max_speed',
- ... index=['falcon', 'falcon', 'parrot', 'parrot'])
- >>> ser.groupby_mean()
- index
- falcon 375.0
- parrot 25.0
- Name: max_speed, dtype: float64
- """
- pass
-
- def contains(self, pattern, case_sensitive=True, na=numpy.nan):
- """
- Return whether each value contains ``pattern``.
-
- In this case, we are illustrating how to use sections, even
- if the example is simple enough and does not require them.
-
- Examples
- --------
- >>> ser = pd.Series('Antelope', 'Lion', 'Zebra', np.nan)
- >>> ser.contains(pattern='a')
- 0 False
- 1 False
- 2 True
- 3 NaN
- dtype: bool
-
- **Case sensitivity**
-
- With ``case_sensitive`` set to ``False`` we can match ``a`` with both
- ``a`` and ``A``:
-
- >>> s.contains(pattern='a', case_sensitive=False)
- 0 True
- 1 False
- 2 True
- 3 NaN
- dtype: bool
-
- **Missing values**
-
- We can fill missing values in the output using the ``na`` parameter:
-
- >>> ser.contains(pattern='a', na=False)
- 0 False
- 1 False
- 2 True
- 3 False
- dtype: bool
- """
- pass
-
-**Bad:**
-
-.. code-block:: python
-
- def method(foo=None, bar=None):
- """
- A sample DataFrame method.
-
- Do not import NumPy and pandas.
-
- Try to use meaningful data, when it makes the example easier
- to understand.
-
- Try to avoid positional arguments like in ``df.method(1)``. They
- can be all right if previously defined with a meaningful name,
- like in ``present_value(interest_rate)``, but avoid them otherwise.
-
- When presenting the behavior with different parameters, do not place
- all the calls one next to the other. Instead, add a short sentence
- explaining what the example shows.
-
- Examples
- --------
- >>> import numpy as np
- >>> import pandas as pd
- >>> df = pd.DataFrame(np.random.randn(3, 3),
- ... columns=('a', 'b', 'c'))
- >>> df.method(1)
- 21
- >>> df.method(bar=14)
- 123
- """
- pass
-
-
-.. _docstring.doctest_tips:
-
-Tips for getting your examples pass the doctests
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Getting the examples pass the doctests in the validation script can sometimes
-be tricky. Here are some attention points:
-
-* Import all needed libraries (except for pandas and NumPy, those are already
- imported as ``import pandas as pd`` and ``import numpy as np``) and define
- all variables you use in the example.
-
-* Try to avoid using random data. However random data might be OK in some
- cases, like if the function you are documenting deals with probability
- distributions, or if the amount of data needed to make the function result
- meaningful is too much, such that creating it manually is very cumbersome.
- In those cases, always use a fixed random seed to make the generated examples
- predictable. Example::
-
- >>> np.random.seed(42)
- >>> df = pd.DataFrame({'normal': np.random.normal(100, 5, 20)})
-
-* If you have a code snippet that wraps multiple lines, you need to use '...'
- on the continued lines: ::
-
- >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'],
- ... columns=['A', 'B'])
-
-* If you want to show a case where an exception is raised, you can do::
-
- >>> pd.to_datetime(["712-01-01"])
- Traceback (most recent call last):
- OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00
-
- It is essential to include the "Traceback (most recent call last):", but for
- the actual error only the error name is sufficient.
-
-* If there is a small part of the result that can vary (e.g. a hash in an object
- representation), you can use ``...`` to represent this part.
-
- If you want to show that ``s.plot()`` returns a matplotlib AxesSubplot object,
- this will fail the doctest ::
-
- >>> s.plot()
-
-
- However, you can do (notice the comment that needs to be added) ::
-
- >>> s.plot() # doctest: +ELLIPSIS
-
-
-
-.. _docstring.example_plots:
-
-Plots in examples
-^^^^^^^^^^^^^^^^^
-
-There are some methods in pandas returning plots. To render the plots generated
-by the examples in the documentation, the ``.. plot::`` directive exists.
-
-To use it, place the next code after the "Examples" header as shown below. The
-plot will be generated automatically when building the documentation.
-
-.. code-block:: python
-
- class Series:
- def plot(self):
- """
- Generate a plot with the ``Series`` data.
-
- Examples
- --------
-
- .. plot::
- :context: close-figs
-
- >>> ser = pd.Series([1, 2, 3])
- >>> ser.plot()
- """
- pass
-
-.. _docstring.sharing:
-
-Sharing docstrings
-------------------
-
-pandas has a system for sharing docstrings, with slight variations, between
-classes. This helps us keep docstrings consistent, while keeping things clear
-for the user reading. It comes at the cost of some complexity when writing.
-
-Each shared docstring will have a base template with variables, like
-``{klass}``. The variables filled in later on using the ``doc`` decorator.
-Finally, docstrings can also be appended to with the ``doc`` decorator.
-
-In this example, we'll create a parent docstring normally (this is like
-``pandas.core.generic.NDFrame``). Then we'll have two children (like
-``pandas.Series`` and ``pandas.DataFrame``). We'll
-substitute the class names in this docstring.
-
-.. code-block:: python
-
- class Parent:
- @doc(klass="Parent")
- def my_function(self):
- """Apply my function to {klass}."""
- ...
-
-
- class ChildA(Parent):
- @doc(Parent.my_function, klass="ChildA")
- def my_function(self):
- ...
-
-
- class ChildB(Parent):
- @doc(Parent.my_function, klass="ChildB")
- def my_function(self):
- ...
-
-The resulting docstrings are
-
-.. code-block:: python
-
- >>> print(Parent.my_function.__doc__)
- Apply my function to Parent.
- >>> print(ChildA.my_function.__doc__)
- Apply my function to ChildA.
- >>> print(ChildB.my_function.__doc__)
- Apply my function to ChildB.
-
-Notice:
-
-1. We "append" the parent docstring to the children docstrings, which are
- initially empty.
-
-Our files will often contain a module-level ``_shared_doc_kwargs`` with some
-common substitution values (things like ``klass``, ``axes``, etc).
-
-You can substitute and append in one shot with something like
-
-.. code-block:: python
-
- @doc(template, **_shared_doc_kwargs)
- def my_function(self):
- ...
-
-where ``template`` may come from a module-level ``_shared_docs`` dictionary
-mapping function names to docstrings. Wherever possible, we prefer using
-``doc``, since the docstring-writing processes is slightly closer to normal.
-
-See ``pandas.core.generic.NDFrame.fillna`` for an example template, and
-``pandas.Series.fillna`` and ``pandas.core.generic.frame.fillna``
-for the filled versions.
diff --git a/doc/source/development/contributing_documentation.rst b/doc/source/development/contributing_documentation.rst
deleted file mode 100644
index 443470e6c50f9..0000000000000
--- a/doc/source/development/contributing_documentation.rst
+++ /dev/null
@@ -1,215 +0,0 @@
-.. _contributing_documentation:
-
-{{ header }}
-
-=================================
-Contributing to the documentation
-=================================
-
-Contributing to the documentation benefits everyone who uses pandas.
-We encourage you to help us improve the documentation, and
-you don't have to be an expert on pandas to do so! In fact,
-there are sections of the docs that are worse off after being written by
-experts. If something in the docs doesn't make sense to you, updating the
-relevant section after you figure it out is a great way to ensure it will help
-the next person. Please visit the `issues page `__
-for a full list of issues that are currently open regarding the
-pandas documentation.
-
-
-
-.. contents:: Documentation:
- :local:
-
-
-About the pandas documentation
---------------------------------
-
-The documentation is written in **reStructuredText**, which is almost like writing
-in plain English, and built using `Sphinx `__. The
-Sphinx Documentation has an excellent `introduction to reST
-`__. Review the Sphinx docs to perform more
-complex changes to the documentation as well.
-
-Some other important things to know about the docs:
-
-* The pandas documentation consists of two parts: the docstrings in the code
- itself and the docs in this folder ``doc/``.
-
- The docstrings provide a clear explanation of the usage of the individual
- functions, while the documentation in this folder consists of tutorial-like
- overviews per topic together with some other information (what's new,
- installation, etc).
-
-* The docstrings follow a pandas convention, based on the **Numpy Docstring
- Standard**. Follow the :ref:`pandas docstring guide ` for detailed
- instructions on how to write a correct docstring.
-
- .. toctree::
- :maxdepth: 2
-
- contributing_docstring.rst
-
-* The tutorials make heavy use of the `IPython directive
- `_ sphinx extension.
- This directive lets you put code in the documentation which will be run
- during the doc build. For example::
-
- .. ipython:: python
-
- x = 2
- x**3
-
- will be rendered as::
-
- In [1]: x = 2
-
- In [2]: x**3
- Out[2]: 8
-
- Almost all code examples in the docs are run (and the output saved) during the
- doc build. This approach means that code examples will always be up to date,
- but it does make the doc building a bit more complex.
-
-* Our API documentation files in ``doc/source/reference`` house the auto-generated
- documentation from the docstrings. For classes, there are a few subtleties
- around controlling which methods and attributes have pages auto-generated.
-
- We have two autosummary templates for classes.
-
- 1. ``_templates/autosummary/class.rst``. Use this when you want to
- automatically generate a page for every public method and attribute on the
- class. The ``Attributes`` and ``Methods`` sections will be automatically
- added to the class' rendered documentation by numpydoc. See ``DataFrame``
- for an example.
-
- 2. ``_templates/autosummary/class_without_autosummary``. Use this when you
- want to pick a subset of methods / attributes to auto-generate pages for.
- When using this template, you should include an ``Attributes`` and
- ``Methods`` section in the class docstring. See ``CategoricalIndex`` for an
- example.
-
- Every method should be included in a ``toctree`` in one of the documentation files in
- ``doc/source/reference``, else Sphinx
- will emit a warning.
-
-The utility script ``scripts/validate_docstrings.py`` can be used to get a csv
-summary of the API documentation. And also validate common errors in the docstring
-of a specific class, function or method. The summary also compares the list of
-methods documented in the files in ``doc/source/reference`` (which is used to generate
-the `API Reference `_ page)
-and the actual public methods.
-This will identify methods documented in ``doc/source/reference`` that are not actually
-class methods, and existing methods that are not documented in ``doc/source/reference``.
-
-
-Updating a pandas docstring
------------------------------
-
-When improving a single function or method's docstring, it is not necessarily
-needed to build the full documentation (see next section).
-However, there is a script that checks a docstring (for example for the ``DataFrame.mean`` method)::
-
- python scripts/validate_docstrings.py pandas.DataFrame.mean
-
-This script will indicate some formatting errors if present, and will also
-run and test the examples included in the docstring.
-Check the :ref:`pandas docstring guide ` for a detailed guide
-on how to format the docstring.
-
-The examples in the docstring ('doctests') must be valid Python code,
-that in a deterministic way returns the presented output, and that can be
-copied and run by users. This can be checked with the script above, and is
-also tested on Travis. A failing doctest will be a blocker for merging a PR.
-Check the :ref:`examples ` section in the docstring guide
-for some tips and tricks to get the doctests passing.
-
-When doing a PR with a docstring update, it is good to post the
-output of the validation script in a comment on github.
-
-.. _contributing.howto-build-docs:
-
-How to build the pandas documentation
----------------------------------------
-
-Requirements
-~~~~~~~~~~~~
-
-First, you need to have a development environment to be able to build pandas
-(see the docs on :ref:`creating a development environment `).
-
-Building the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-So how do you build the docs? Navigate to your local
-``doc/`` directory in the console and run::
-
- python make.py html
-
-Then you can find the HTML output in the folder ``doc/build/html/``.
-
-The first time you build the docs, it will take quite a while because it has to run
-all the code examples and build all the generated docstring pages. In subsequent
-evocations, sphinx will try to only build the pages that have been modified.
-
-If you want to do a full clean build, do::
-
- python make.py clean
- python make.py html
-
-You can tell ``make.py`` to compile only a single section of the docs, greatly
-reducing the turn-around time for checking your changes.
-
-::
-
- # omit autosummary and API section
- python make.py clean
- python make.py --no-api
-
- # compile the docs with only a single section, relative to the "source" folder.
- # For example, compiling only this guide (doc/source/development/contributing.rst)
- python make.py clean
- python make.py --single development/contributing.rst
-
- # compile the reference docs for a single function
- python make.py clean
- python make.py --single pandas.DataFrame.join
-
- # compile whatsnew and API section (to resolve links in the whatsnew)
- python make.py clean
- python make.py --whatsnew
-
-For comparison, a full documentation build may take 15 minutes, but a single
-section may take 15 seconds. Subsequent builds, which only process portions
-you have changed, will be faster.
-
-The build will automatically use the number of cores available on your machine
-to speed up the documentation build. You can override this::
-
- python make.py html --num-jobs 4
-
-Open the following file in a web browser to see the full documentation you
-just built ``doc/build/html/index.html``.
-
-And you'll have the satisfaction of seeing your new and improved documentation!
-
-.. _contributing.dev_docs:
-
-Building main branch documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When pull requests are merged into the pandas ``main`` branch, the main parts of
-the documentation are also built by Travis-CI. These docs are then hosted `here
-`__, see also
-the :any:`Continuous Integration ` section.
-
-Previewing changes
-------------------
-
-Once, the pull request is submitted, GitHub Actions will automatically build the
-documentation. To view the built site:
-
-#. Wait for the ``CI / Web and docs`` check to complete.
-#. Click ``Details`` next to it.
-#. From the ``Artifacts`` drop-down, click ``docs`` or ``website`` to download
- the site as a ZIP file.
diff --git a/doc/source/development/contributing_environment.rst b/doc/source/development/contributing_environment.rst
deleted file mode 100644
index d7b779debcd5e..0000000000000
--- a/doc/source/development/contributing_environment.rst
+++ /dev/null
@@ -1,313 +0,0 @@
-.. _contributing_environment:
-
-{{ header }}
-
-==================================
-Creating a development environment
-==================================
-
-To test out code changes, you'll need to build pandas from source, which
-requires a C/C++ compiler and Python environment. If you're making documentation
-changes, you can skip to :ref:`contributing to the documentation ` but if you skip
-creating the development environment you won't be able to build the documentation
-locally before pushing your changes. It's recommended to also install the :ref:`pre-commit hooks `.
-
-.. toctree::
- :maxdepth: 2
- :hidden:
-
- contributing_gitpod.rst
-
-Step 1: install a C compiler
-----------------------------
-
-How to do this will depend on your platform. If you choose to use ``Docker`` or ``GitPod``
-in the next step, then you can skip this step.
-
-**Windows**
-
-You will need `Build Tools for Visual Studio 2022
-`_.
-
-.. note::
- You DO NOT need to install Visual Studio 2022.
- You only need "Build Tools for Visual Studio 2022" found by
- scrolling down to "All downloads" -> "Tools for Visual Studio".
- In the installer, select the "Desktop development with C++" Workloads.
-
- If you encounter an error indicating ``cl.exe`` is not found when building with Meson,
- reopen the installer and also select the optional component
- **MSVC v142 - VS 2019 C++ x64/x86 build tools** in the right pane for installation.
-
-Alternatively, you can install the necessary components on the commandline using
-`vs_BuildTools.exe `_
-
-Alternatively, you could use the `WSL `_
-and consult the ``Linux`` instructions below.
-
-**macOS**
-
-To use the :ref:`conda `-based compilers, you will need to install the
-Developer Tools using ``xcode-select --install``.
-
-If you prefer to use a different compiler, general information can be found here:
-https://devguide.python.org/setup/#macos
-
-**Linux**
-
-For Linux-based :ref:`conda ` installations, you won't have to install any
-additional components outside of the conda environment. The instructions
-below are only needed if your setup isn't based on conda environments.
-
-Some Linux distributions will come with a pre-installed C compiler. To find out
-which compilers (and versions) are installed on your system::
-
- # for Debian/Ubuntu:
- dpkg --list | grep compiler
- # for Red Hat/RHEL/CentOS/Fedora:
- yum list installed | grep -i --color compiler
-
-`GCC (GNU Compiler Collection) `_, is a widely used
-compiler, which supports C and a number of other languages. If GCC is listed
-as an installed compiler nothing more is required.
-
-If no C compiler is installed, or you wish to upgrade, or you're using a different
-Linux distribution, consult your favorite search engine for compiler installation/update
-instructions.
-
-Let us know if you have any difficulties by opening an issue or reaching out on our contributor
-community :ref:`Slack `.
-
-Step 2: create an isolated environment
-----------------------------------------
-
-Before we begin, please:
-
-* Make sure that you have :any:`cloned the repository `
-* ``cd`` to the pandas source directory you just created with the clone command
-
-.. _contributing.conda:
-
-Option 1: using conda (recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* Install miniforge to get `conda `_
-* Create and activate the ``pandas-dev`` conda environment using the following commands:
-
-.. code-block:: bash
-
- conda env create --file environment.yml
- conda activate pandas-dev
-
-.. _contributing.pip:
-
-Option 2: using pip
-~~~~~~~~~~~~~~~~~~~
-
-You'll need to have at least the :ref:`minimum Python version ` that pandas supports.
-You also need to have ``setuptools`` 51.0.0 or later to build pandas.
-
-**Unix**/**macOS with virtualenv**
-
-.. code-block:: bash
-
- # Create a virtual environment
- # Use an ENV_DIR of your choice. We'll use ~/virtualenvs/pandas-dev
- # Any parent directories should already exist
- python3 -m venv ~/virtualenvs/pandas-dev
-
- # Activate the virtualenv
- . ~/virtualenvs/pandas-dev/bin/activate
-
- # Install the build dependencies
- python -m pip install -r requirements-dev.txt
-
-**Unix**/**macOS with pyenv**
-
-Consult the docs for setting up pyenv `here `__.
-
-.. code-block:: bash
-
- # Create a virtual environment
- # Use an ENV_DIR of your choice. We'll use ~/Users//.pyenv/versions/pandas-dev
- pyenv virtualenv
-
- # For instance:
- pyenv virtualenv 3.10 pandas-dev
-
- # Activate the virtualenv
- pyenv activate pandas-dev
-
- # Now install the build dependencies in the cloned pandas repo
- python -m pip install -r requirements-dev.txt
-
-**Windows**
-
-Below is a brief overview on how to set-up a virtual environment with Powershell
-under Windows. For details please refer to the
-`official virtualenv user guide `__.
-
-Use an ENV_DIR of your choice. We'll use ``~\\virtualenvs\\pandas-dev`` where
-``~`` is the folder pointed to by either ``$env:USERPROFILE`` (Powershell) or
-``%USERPROFILE%`` (cmd.exe) environment variable. Any parent directories
-should already exist.
-
-.. code-block:: powershell
-
- # Create a virtual environment
- python -m venv $env:USERPROFILE\virtualenvs\pandas-dev
-
- # Activate the virtualenv. Use activate.bat for cmd.exe
- ~\virtualenvs\pandas-dev\Scripts\Activate.ps1
-
- # Install the build dependencies
- python -m pip install -r requirements-dev.txt
-
-Option 3: using Docker
-~~~~~~~~~~~~~~~~~~~~~~
-
-pandas provides a ``DockerFile`` in the root directory to build a Docker image
-with a full pandas development environment.
-
-**Docker Commands**
-
-Build the Docker image::
-
- # Build the image
- docker build -t pandas-dev .
-
-Run Container::
-
- # Run a container and bind your local repo to the container
- # This command assumes you are running from your local repo
- # but if not alter ${PWD} to match your local repo path
- docker run -it --rm -v ${PWD}:/home/pandas pandas-dev
-
-*Even easier, you can integrate Docker with the following IDEs:*
-
-**Visual Studio Code**
-
-You can use the DockerFile to launch a remote session with Visual Studio Code,
-a popular free IDE, using the ``.devcontainer.json`` file.
-See https://code.visualstudio.com/docs/remote/containers for details.
-
-**PyCharm (Professional)**
-
-Enable Docker support and use the Services tool window to build and manage images as well as
-run and interact with containers.
-See https://www.jetbrains.com/help/pycharm/docker.html for details.
-
-Option 4: using Gitpod
-~~~~~~~~~~~~~~~~~~~~~~
-
-Gitpod is an open-source platform that automatically creates the correct development
-environment right in your browser, reducing the need to install local development
-environments and deal with incompatible dependencies.
-
-If you are a Windows user, unfamiliar with using the command line or building pandas
-for the first time, it is often faster to build with Gitpod. Here are the in-depth instructions
-for :ref:`building pandas with GitPod `.
-
-Step 3: build and install pandas
---------------------------------
-
-There are currently two supported ways of building pandas, pip/meson and setuptools(setup.py).
-Historically, pandas has only supported using setuptools to build pandas. However, this method
-requires a lot of convoluted code in setup.py and also has many issues in compiling pandas in parallel
-due to limitations in setuptools.
-
-The newer build system, invokes the meson backend through pip (via a `PEP 517 `_ build).
-It automatically uses all available cores on your CPU, and also avoids the need for manual rebuilds by
-rebuilding automatically whenever pandas is imported (with an editable install).
-
-For these reasons, you should compile pandas with meson.
-Because the meson build system is newer, you may find bugs/minor issues as it matures. You can report these bugs
-`here `_.
-
-To compile pandas with meson, run::
-
- # Build and install pandas
- # By default, this will print verbose output
- # showing the "rebuild" taking place on import (see section below for explanation)
- # If you do not want to see this, omit everything after --no-build-isolation
- python -m pip install -ve . --no-build-isolation -Ceditable-verbose=true
-
-.. note::
- The version number is pulled from the latest repository tag. Be sure to fetch the latest tags from upstream
- before building::
-
- # set the upstream repository, if not done already, and fetch the latest tags
- git remote add upstream https://github.com/pandas-dev/pandas.git
- git fetch upstream --tags
-
-**Build options**
-
-It is possible to pass options from the pip frontend to the meson backend if you would like to configure your
-install. Occasionally, you'll want to use this to adjust the build directory, and/or toggle debug/optimization levels.
-
-You can pass a build directory to pandas by appending ``-Cbuilddir="your builddir here"`` to your pip command.
-This option allows you to configure where meson stores your built C extensions, and allows for fast rebuilds.
-
-Sometimes, it might be useful to compile pandas with debugging symbols, when debugging C extensions.
-Appending ``-Csetup-args="-Ddebug=true"`` will do the trick.
-
-With pip, it is possible to chain together multiple config settings. For example, specifying both a build directory
-and building with debug symbols would look like
-``-Cbuilddir="your builddir here" -Csetup-args="-Dbuildtype=debug"``.
-
-**Compiling pandas with setup.py**
-
-.. note::
- This method of compiling pandas will be deprecated and removed very soon, as the meson backend matures.
-
-To compile pandas with setuptools, run::
-
- python setup.py develop
-
-.. note::
- If pandas is already installed (via meson), you have to uninstall it first::
-
- python -m pip uninstall pandas
-
-This is because python setup.py develop will not uninstall the loader script that ``meson-python``
-uses to import the extension from the build folder, which may cause errors such as an
-``FileNotFoundError`` to be raised.
-
-.. note::
- You will need to repeat this step each time the C extensions change, for example
- if you modified any file in ``pandas/_libs`` or if you did a fetch and merge from ``upstream/main``.
-
-**Checking the build**
-
-At this point you should be able to import pandas from your locally built version::
-
- $ python
- >>> import pandas
- >>> print(pandas.__version__) # note: the exact output may differ
- 2.0.0.dev0+880.g2b9e661fbb.dirty
-
-
-At this point you may want to try
-`running the test suite `_.
-
-**Keeping up to date with the latest build**
-
-When building pandas with meson, importing pandas will automatically trigger a rebuild, even when C/Cython files are modified.
-By default, no output will be produced by this rebuild (the import will just take longer). If you would like to see meson's
-output when importing pandas, you can set the environment variable ``MESONPY_EDITABLE_VERBOSE``. For example, this would be::
-
- # On Linux/macOS
- MESONPY_EDITABLE_VERBOSE=1 python
-
- # Windows
- set MESONPY_EDITABLE_VERBOSE=1 # Only need to set this once per session
- python
-
-If you would like to see this verbose output every time, you can set the ``editable-verbose`` config setting to ``true`` like so::
-
- python -m pip install -ve . -Ceditable-verbose=true
-
-.. tip::
- If you ever find yourself wondering whether setuptools or meson was used to build your pandas,
- you can check the value of ``pandas._built_with_meson``, which will be true if meson was used
- to compile pandas.
diff --git a/doc/source/development/contributing_gitpod.rst b/doc/source/development/contributing_gitpod.rst
deleted file mode 100644
index 447b7b20a8ae5..0000000000000
--- a/doc/source/development/contributing_gitpod.rst
+++ /dev/null
@@ -1,274 +0,0 @@
-.. _contributing-gitpod:
-
-Using Gitpod for pandas development
-===================================
-
-This section of the documentation will guide you through:
-
-* using Gitpod for your pandas development environment
-* creating a personal fork of the pandas repository on GitHub
-* a quick tour of pandas and VSCode
-* working on the pandas documentation in Gitpod
-
-Gitpod
-------
-
-`Gitpod`_ is an open-source platform for automated and ready-to-code
-development environments. It enables developers to describe their dev
-environment as code and start instant and fresh development environments for
-each new task directly from your browser. This reduces the need to install local
-development environments and deal with incompatible dependencies.
-
-
-Gitpod GitHub integration
--------------------------
-
-To be able to use Gitpod, you will need to have the Gitpod app installed on your
-GitHub account, so if
-you do not have an account yet, you will need to create one first.
-
-To get started just login at `Gitpod`_, and grant the appropriate permissions to GitHub.
-
-We have built a python 3.10 environment and all development dependencies will
-install when the environment starts.
-
-
-Forking the pandas repository
------------------------------
-
-The best way to work on pandas as a contributor is by making a fork of the
-repository first.
-
-#. Browse to the `pandas repository on GitHub`_ and `create your own fork`_.
-
-#. Browse to your fork. Your fork will have a URL like
- https://github.com/noatamir/pandas-dev, except with your GitHub username in place of
- ``noatamir``.
-
-Starting Gitpod
----------------
-Once you have authenticated to Gitpod through GitHub, you can install the
-`Gitpod Chromium or Firefox browser extension `_
-which will add a **Gitpod** button next to the **Code** button in the
-repository:
-
-.. image:: ./gitpod-imgs/pandas-github.png
- :alt: pandas repository with Gitpod button screenshot
-
-#. If you install the extension - you can click the **Gitpod** button to start
- a new workspace.
-
-#. Alternatively, if you do not want to install the browser extension, you can
- visit https://gitpod.io/#https://github.com/USERNAME/pandas replacing
- ``USERNAME`` with your GitHub username.
-
-#. In both cases, this will open a new tab on your web browser and start
- building your development environment. Please note this can take a few
- minutes.
-
-#. Once the build is complete, you will be directed to your workspace,
- including the VSCode editor and all the dependencies you need to work on
- pandas. The first time you start your workspace, you will notice that there
- might be some actions running. This will ensure that you have a development
- version of pandas installed.
-
-#. When your workspace is ready, you can :ref:`test the build` by
- entering::
-
- $ python -m pytest pandas
-
- Note that this command takes a while to run, so once you've confirmed it's running you may want to cancel it using ctrl-c.
-
-Quick workspace tour
---------------------
-Gitpod uses VSCode as the editor. If you have not used this editor before, you
-can check the Getting started `VSCode docs`_ to familiarize yourself with it.
-
-Your workspace will look similar to the image below:
-
-.. image:: ./gitpod-imgs/gitpod-workspace.png
- :alt: Gitpod workspace screenshot
-
-We have marked some important sections in the editor:
-
-#. Your current Python interpreter - by default, this is ``pandas-dev`` and
- should be displayed in the status bar and on your terminal. You do not need
- to activate the conda environment as this will always be activated for you.
-#. Your current branch is always displayed in the status bar. You can also use
- this button to change or create branches.
-#. GitHub Pull Requests extension - you can use this to work with Pull Requests
- from your workspace.
-#. Marketplace extensions - we have added some essential extensions to the pandas
- Gitpod. Still, you can also install other extensions or syntax highlighting
- themes for your user, and these will be preserved for you.
-#. Your workspace directory - by default, it is ``/workspace/pandas-dev``. **Do not
- change this** as this is the only directory preserved in Gitpod.
-
-We have also pre-installed a few tools and VSCode extensions to help with the
-development experience:
-
-* `VSCode rst extension `_
-* `Markdown All in One `_
-* `VSCode GitLens extension `_
-* `VSCode Git Graph extension `_
-
-Development workflow with Gitpod
---------------------------------
-The :ref:`contributing` section of this documentation contains
-information regarding the pandas development workflow. Make sure to check this
-before working on your contributions.
-
-When using Gitpod, git is pre configured for you:
-
-#. You do not need to configure your git username, and email as this should be
- done for you as you authenticated through GitHub. Unless you are using GitHub
- feature to keep email address private. You can check the git
- configuration with the command ``git config --list`` in your terminal. Use
- ``git config --global user.email “your-secret-email@users.noreply.github.com”``
- to set your email address to the one you use to make commits with your github
- profile.
-#. As you started your workspace from your own pandas fork, you will by default
- have both ``upstream`` and ``origin`` added as remotes. You can verify this by
- typing ``git remote`` on your terminal or by clicking on the **branch name**
- on the status bar (see image below).
-
- .. image:: ./gitpod-imgs/pandas-gitpod-branches.png
- :alt: Gitpod workspace branches plugin screenshot
-
-Rendering the pandas documentation
-----------------------------------
-You can find the detailed documentation on how rendering the documentation with
-Sphinx works in the :ref:`contributing.howto-build-docs` section. To build the full
-docs you need to run the following command in the ``/doc`` directory::
-
- $ cd doc
- $ python make.py html
-
-Alternatively you can build a single page with::
-
- python make.py --single development/contributing_gitpod.rst
-
-You have two main options to render the documentation in Gitpod.
-
-Option 1: using Liveserve
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-#. View the documentation in ``pandas/doc/build/html``.
-#. To see the rendered version of a page, you can right-click on the ``.html``
- file and click on **Open with Live Serve**. Alternatively, you can open the
- file in the editor and click on the **Go live** button on the status bar.
-
- .. image:: ./gitpod-imgs/vscode-statusbar.png
- :alt: Gitpod workspace VSCode start live serve screenshot
-
-#. A simple browser will open to the right-hand side of the editor. We recommend
- closing it and click on the **Open in browser** button in the pop-up.
-#. To stop the server click on the **Port: 5500** button on the status bar.
-
-Option 2: using the rst extension
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A quick and easy way to see live changes in a ``.rst`` file as you work on it
-uses the rst extension with docutils.
-
-.. note:: This will generate a simple live preview of the document without the
- ``html`` theme, and some backlinks might not be added correctly. But it is an
- easy and lightweight way to get instant feedback on your work, without
- building the html files.
-
-#. Open any of the source documentation files located in ``doc/source`` in the
- editor.
-#. Open VSCode Command Palette with :kbd:`Cmd-Shift-P` in Mac or
- :kbd:`Ctrl-Shift-P` in Linux and Windows. Start typing "restructured"
- and choose either "Open preview" or "Open preview to the Side".
-
- .. image:: ./gitpod-imgs/vscode-rst.png
- :alt: Gitpod workspace VSCode open rst screenshot
-
-#. As you work on the document, you will see a live rendering of it on the editor.
-
- .. image:: ./gitpod-imgs/rst-rendering.png
- :alt: Gitpod workspace VSCode rst rendering screenshot
-
-If you want to see the final output with the ``html`` theme you will need to
-rebuild the docs with ``make html`` and use Live Serve as described in option 1.
-
-FAQ's and troubleshooting
--------------------------
-
-How long is my Gitpod workspace kept for?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Your stopped workspace will be kept for 14 days and deleted afterwards if you do
-not use them.
-
-Can I come back to a previous workspace?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Yes, let's say you stepped away for a while and you want to carry on working on
-your pandas contributions. You need to visit https://gitpod.io/workspaces and
-click on the workspace you want to spin up again. All your changes will be there
-as you last left them.
-
-Can I install additional VSCode extensions?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Absolutely! Any extensions you installed will be installed in your own workspace
-and preserved.
-
-I registered on Gitpod but I still cannot see a ``Gitpod`` button in my repositories.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Head to https://gitpod.io/integrations and make sure you are logged in.
-Hover over GitHub and click on the three buttons that appear on the right.
-Click on edit permissions and make sure you have ``user:email``,
-``read:user``, and ``public_repo`` checked. Click on **Update Permissions**
-and confirm the changes in the GitHub application page.
-
-.. image:: ./gitpod-imgs/gitpod-edit-permissions-gh.png
- :alt: Gitpod integrations - edit GH permissions screenshot
-
-How long does my workspace stay active if I'm not using it?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you keep your workspace open in a browser tab but don't interact with it,
-it will shut down after 30 minutes. If you close the browser tab, it will
-shut down after 3 minutes.
-
-My terminal is blank - there is no cursor and it's completely unresponsive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Unfortunately this is a known-issue on Gitpod's side. You can sort this
-issue in two ways:
-
-#. Create a new Gitpod workspace altogether.
-#. Head to your `Gitpod dashboard `_ and locate
- the running workspace. Hover on it and click on the **three dots menu**
- and then click on **Stop**. When the workspace is completely stopped you
- can click on its name to restart it again.
-
-.. image:: ./gitpod-imgs/gitpod-dashboard-stop.png
- :alt: Gitpod dashboard and workspace menu screenshot
-
-I authenticated through GitHub but I still cannot commit to the repository through Gitpod.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Head to https://gitpod.io/integrations and make sure you are logged in.
-Hover over GitHub and click on the three buttons that appear on the right.
-Click on edit permissions and make sure you have ``public_repo`` checked.
-Click on **Update Permissions** and confirm the changes in the
-GitHub application page.
-
-.. image:: ./gitpod-imgs/gitpod-edit-permissions-repo.png
- :alt: Gitpod integrations - edit GH repository permissions screenshot
-
-Acknowledgments
----------------
-
-This page is lightly adapted from the `NumPy`_ project .
-
-.. _Gitpod: https://www.gitpod.io/
-.. _pandas repository on GitHub: https://github.com/pandas-dev/pandas
-.. _create your own fork: https://help.github.com/en/articles/fork-a-repo
-.. _VSCode docs: https://code.visualstudio.com/docs/getstarted/tips-and-tricks
-.. _NumPy: https://www.numpy.org/
diff --git a/doc/source/development/copy_on_write.rst b/doc/source/development/copy_on_write.rst
deleted file mode 100644
index 9a2309b8a77a3..0000000000000
--- a/doc/source/development/copy_on_write.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-.. _copy_on_write_dev:
-
-{{ header }}
-
-*************
-Copy on write
-*************
-
-Copy on Write is a mechanism to simplify the indexing API and improve
-performance through avoiding copies if possible.
-CoW means that any DataFrame or Series derived from another in any way always
-behaves as a copy. An explanation on how to use Copy on Write efficiently can be
-found :ref:`here `.
-
-Reference tracking
-------------------
-
-To be able to determine if we have to make a copy when writing into a DataFrame,
-we have to be aware if the values are shared with another DataFrame. pandas
-keeps track of all ``Blocks`` that share values with another block internally to
-be able to tell when a copy needs to be triggered. The reference tracking
-mechanism is implemented on the Block level.
-
-We use a custom reference tracker object, ``BlockValuesRefs``, that keeps
-track of every block, whose values share memory with each other. The reference
-is held through a weak-reference. Every pair of blocks that share some memory should
-point to the same ``BlockValuesRefs`` object. If one block goes out of
-scope, the reference to this block dies. As a consequence, the reference tracker
-object always knows how many blocks are alive and share memory.
-
-Whenever a :class:`DataFrame` or :class:`Series` object is sharing data with another
-object, it is required that each of those objects have its own BlockManager and Block
-objects. Thus, in other words, one Block instance (that is held by a DataFrame, not
-necessarily for intermediate objects) should always be uniquely used for only
-a single DataFrame/Series object. For example, when you want to use the same
-Block for another object, you can create a shallow copy of the Block instance
-with ``block.copy(deep=False)`` (which will create a new Block instance with
-the same underlying values and which will correctly set up the references).
-
-We can ask the reference tracking object if there is another block alive that shares
-data with us before writing into the values. We can trigger a copy before
-writing if there is in fact another block alive.
diff --git a/doc/source/development/debugging_extensions.rst b/doc/source/development/debugging_extensions.rst
deleted file mode 100644
index c8127e0cc2996..0000000000000
--- a/doc/source/development/debugging_extensions.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-.. _debugging_c_extensions:
-
-{{ header }}
-
-======================
-Debugging C extensions
-======================
-
-pandas uses Cython and C/C++ `extension modules `_ to optimize performance. Unfortunately, the standard Python debugger does not allow you to step into these extensions. Cython extensions can be debugged with the `Cython debugger `_ and C/C++ extensions can be debugged using the tools shipped with your platform's compiler.
-
-For Python developers with limited or no C/C++ experience this can seem a daunting task. Core developer Will Ayd has written a 3 part blog series to help guide you from the standard Python debugger into these other tools:
-
-1. `Fundamental Python Debugging Part 1 - Python `_
-2. `Fundamental Python Debugging Part 2 - Python Extensions `_
-3. `Fundamental Python Debugging Part 3 - Cython Extensions `_
-
-Debugging locally
------------------
-
-By default building pandas from source will generate a release build. To generate a development build you can type::
-
- pip install -ve . --no-build-isolation -Cbuilddir="debug" -Csetup-args="-Dbuildtype=debug"
-
-.. note::
-
- conda environments update CFLAGS/CPPFLAGS with flags that are geared towards generating releases, and may work counter towards usage in a development environment. If using conda, you should unset these environment variables via ``export CFLAGS=`` and ``export CPPFLAGS=``
-
-By specifying ``builddir="debug"`` all of the targets will be built and placed in the debug directory relative to the project root. This helps to keep your debug and release artifacts separate; you are of course able to choose a different directory name or omit altogether if you do not care to separate build types.
-
-Using Docker
-------------
-
-To simplify the debugging process, pandas has created a Docker image with a debug build of Python and the gdb/Cython debuggers pre-installed. You may either ``docker pull pandas/pandas-debug`` to get access to this image or build it from the ``tooling/debug`` folder locally.
-
-You can then mount your pandas repository into this image via:
-
-.. code-block:: sh
-
- docker run --rm -it -w /data -v ${PWD}:/data pandas/pandas-debug
-
-Inside the image, you can use meson to build/install pandas and place the build artifacts into a ``debug`` folder using a command as follows:
-
-.. code-block:: sh
-
- python -m pip install -ve . --no-build-isolation -Cbuilddir="debug" -Csetup-args="-Dbuildtype=debug"
-
-If planning to use cygdb, the files required by that application are placed within the build folder. So you have to first ``cd`` to the build folder, then start that application.
-
-.. code-block:: sh
-
- cd debug
- cygdb
-
-Within the debugger you can use `cygdb commands `_ to navigate cython extensions.
-
-Editor support
---------------
-
-The meson build system generates a `compilation database `_ automatically and places it in the build directory. Many language servers and IDEs can use this information to provide code-completion, go-to-definition and error checking support as you type.
-
-How each language server / IDE chooses to look for the compilation database may vary. When in doubt you may want to create a symlink at the root of the project that points to the compilation database in your build directory. Assuming you used *debug* as your directory name, you can run::
-
- ln -s debug/compile_commands.json .
diff --git a/doc/source/development/developer.rst b/doc/source/development/developer.rst
deleted file mode 100644
index 21a840fbe9a5f..0000000000000
--- a/doc/source/development/developer.rst
+++ /dev/null
@@ -1,187 +0,0 @@
-.. _developer:
-
-{{ header }}
-
-.. currentmodule:: pandas
-
-*********
-Developer
-*********
-
-This section will focus on downstream applications of pandas.
-
-.. _apache.parquet:
-
-Storing pandas DataFrame objects in Apache Parquet format
----------------------------------------------------------
-
-The `Apache Parquet `__ format
-provides key-value metadata at the file and column level, stored in the footer
-of the Parquet file:
-
-.. code-block:: shell
-
- 5: optional list key_value_metadata
-
-where ``KeyValue`` is
-
-.. code-block:: shell
-
- struct KeyValue {
- 1: required string key
- 2: optional string value
- }
-
-So that a ``pandas.DataFrame`` can be faithfully reconstructed, we store a
-``pandas`` metadata key in the ``FileMetaData`` with the value stored as :
-
-.. code-block:: text
-
- {'index_columns': [, , ...],
- 'column_indexes': [, , ..., ],
- 'columns': [, , ...],
- 'pandas_version': $VERSION,
- 'creator': {
- 'library': $LIBRARY,
- 'version': $LIBRARY_VERSION
- }}
-
-The "descriptor" values ```` in the ``'index_columns'`` field are
-strings (referring to a column) or dictionaries with values as described below.
-
-The ````/```` and so forth are dictionaries containing the metadata
-for each column, *including the index columns*. This has JSON form:
-
-.. code-block:: text
-
- {'name': column_name,
- 'field_name': parquet_column_name,
- 'pandas_type': pandas_type,
- 'numpy_type': numpy_type,
- 'metadata': metadata}
-
-See below for the detailed specification for these.
-
-Index metadata descriptors
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``RangeIndex`` can be stored as metadata only, not requiring serialization. The
-descriptor format for these as is follows:
-
-.. code-block:: python
-
- index = pd.RangeIndex(0, 10, 2)
- {
- "kind": "range",
- "name": index.name,
- "start": index.start,
- "stop": index.stop,
- "step": index.step,
- }
-
-Other index types must be serialized as data columns along with the other
-DataFrame columns. The metadata for these is a string indicating the name of
-the field in the data columns, for example ``'__index_level_0__'``.
-
-If an index has a non-None ``name`` attribute, and there is no other column
-with a name matching that value, then the ``index.name`` value can be used as
-the descriptor. Otherwise (for unnamed indexes and ones with names colliding
-with other column names) a disambiguating name with pattern matching
-``__index_level_\d+__`` should be used. In cases of named indexes as data
-columns, ``name`` attribute is always stored in the column descriptors as
-above.
-
-Column metadata
-~~~~~~~~~~~~~~~
-
-``pandas_type`` is the logical type of the column, and is one of:
-
-* Boolean: ``'bool'``
-* Integers: ``'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64'``
-* Floats: ``'float16', 'float32', 'float64'``
-* Date and Time Types: ``'datetime', 'datetimetz', 'timedelta'``
-* String: ``'unicode', 'bytes'``
-* Categorical: ``'categorical'``
-* Other Python objects: ``'object'``
-
-The ``numpy_type`` is the physical storage type of the column, which is the
-result of ``str(dtype)`` for the underlying NumPy array that holds the data. So
-for ``datetimetz`` this is ``datetime64[ns]`` and for categorical, it may be
-any of the supported integer categorical types.
-
-The ``metadata`` field is ``None`` except for:
-
-* ``datetimetz``: ``{'timezone': zone, 'unit': 'ns'}``, e.g. ``{'timezone',
- 'America/New_York', 'unit': 'ns'}``. The ``'unit'`` is optional, and if
- omitted it is assumed to be nanoseconds.
-* ``categorical``: ``{'num_categories': K, 'ordered': is_ordered, 'type': $TYPE}``
-
- * Here ``'type'`` is optional, and can be a nested pandas type specification
- here (but not categorical)
-
-* ``unicode``: ``{'encoding': encoding}``
-
- * The encoding is optional, and if not present is UTF-8
-
-* ``object``: ``{'encoding': encoding}``. Objects can be serialized and stored
- in ``BYTE_ARRAY`` Parquet columns. The encoding can be one of:
-
- * ``'pickle'``
- * ``'bson'``
- * ``'json'``
-
-* ``timedelta``: ``{'unit': 'ns'}``. The ``'unit'`` is optional, and if omitted
- it is assumed to be nanoseconds. This metadata is optional altogether
-
-For types other than these, the ``'metadata'`` key can be
-omitted. Implementations can assume ``None`` if the key is not present.
-
-As an example of fully-formed metadata:
-
-.. code-block:: text
-
- {'index_columns': ['__index_level_0__'],
- 'column_indexes': [
- {'name': None,
- 'field_name': 'None',
- 'pandas_type': 'unicode',
- 'numpy_type': 'object',
- 'metadata': {'encoding': 'UTF-8'}}
- ],
- 'columns': [
- {'name': 'c0',
- 'field_name': 'c0',
- 'pandas_type': 'int8',
- 'numpy_type': 'int8',
- 'metadata': None},
- {'name': 'c1',
- 'field_name': 'c1',
- 'pandas_type': 'bytes',
- 'numpy_type': 'object',
- 'metadata': None},
- {'name': 'c2',
- 'field_name': 'c2',
- 'pandas_type': 'categorical',
- 'numpy_type': 'int16',
- 'metadata': {'num_categories': 1000, 'ordered': False}},
- {'name': 'c3',
- 'field_name': 'c3',
- 'pandas_type': 'datetimetz',
- 'numpy_type': 'datetime64[ns]',
- 'metadata': {'timezone': 'America/Los_Angeles'}},
- {'name': 'c4',
- 'field_name': 'c4',
- 'pandas_type': 'object',
- 'numpy_type': 'object',
- 'metadata': {'encoding': 'pickle'}},
- {'name': None,
- 'field_name': '__index_level_0__',
- 'pandas_type': 'int64',
- 'numpy_type': 'int64',
- 'metadata': None}
- ],
- 'pandas_version': '1.4.0',
- 'creator': {
- 'library': 'pyarrow',
- 'version': '0.13.0'
- }}
diff --git a/doc/source/development/extending.rst b/doc/source/development/extending.rst
deleted file mode 100644
index e67829b8805eb..0000000000000
--- a/doc/source/development/extending.rst
+++ /dev/null
@@ -1,536 +0,0 @@
-.. _extending:
-
-{{ header }}
-
-****************
-Extending pandas
-****************
-
-While pandas provides a rich set of methods, containers, and data types, your
-needs may not be fully satisfied. pandas offers a few options for extending
-pandas.
-
-.. _extending.register-accessors:
-
-Registering custom accessors
-----------------------------
-
-Libraries can use the decorators
-:func:`pandas.api.extensions.register_dataframe_accessor`,
-:func:`pandas.api.extensions.register_series_accessor`, and
-:func:`pandas.api.extensions.register_index_accessor`, to add additional
-"namespaces" to pandas objects. All of these follow a similar convention: you
-decorate a class, providing the name of attribute to add. The class's
-``__init__`` method gets the object being decorated. For example:
-
-.. code-block:: python
-
- @pd.api.extensions.register_dataframe_accessor("geo")
- class GeoAccessor:
- def __init__(self, pandas_obj):
- self._validate(pandas_obj)
- self._obj = pandas_obj
-
- @staticmethod
- def _validate(obj):
- # verify there is a column latitude and a column longitude
- if "latitude" not in obj.columns or "longitude" not in obj.columns:
- raise AttributeError("Must have 'latitude' and 'longitude'.")
-
- @property
- def center(self):
- # return the geographic center point of this DataFrame
- lat = self._obj.latitude
- lon = self._obj.longitude
- return (float(lon.mean()), float(lat.mean()))
-
- def plot(self):
- # plot this array's data on a map, e.g., using Cartopy
- pass
-
-Now users can access your methods using the ``geo`` namespace:
-
- >>> ds = pd.DataFrame(
- ... {"longitude": np.linspace(0, 10), "latitude": np.linspace(0, 20)}
- ... )
- >>> ds.geo.center
- (5.0, 10.0)
- >>> ds.geo.plot()
- # plots data on a map
-
-This can be a convenient way to extend pandas objects without subclassing them.
-If you write a custom accessor, make a pull request adding it to our
-`ecosystem `_ page.
-
-We highly recommend validating the data in your accessor's ``__init__``.
-In our ``GeoAccessor``, we validate that the data contains the expected columns,
-raising an ``AttributeError`` when the validation fails.
-For a ``Series`` accessor, you should validate the ``dtype`` if the accessor
-applies only to certain dtypes.
-
-
-.. _extending.extension-types:
-
-Extension types
----------------
-
-.. note::
-
- The :class:`pandas.api.extensions.ExtensionDtype` and :class:`pandas.api.extensions.ExtensionArray` APIs were
- experimental prior to pandas 1.5. Starting with version 1.5, future changes will follow
- the :ref:`pandas deprecation policy `.
-
-pandas defines an interface for implementing data types and arrays that *extend*
-NumPy's type system. pandas itself uses the extension system for some types
-that aren't built into NumPy (categorical, period, interval, datetime with
-timezone).
-
-Libraries can define a custom array and data type. When pandas encounters these
-objects, they will be handled properly (i.e. not converted to an ndarray of
-objects). Many methods like :func:`pandas.isna` will dispatch to the extension
-type's implementation.
-
-If you're building a library that implements the interface, please publicize it
-on `the ecosystem page `_.
-
-The interface consists of two classes.
-
-:class:`~pandas.api.extensions.ExtensionDtype`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A :class:`pandas.api.extensions.ExtensionDtype` is similar to a ``numpy.dtype`` object. It describes the
-data type. Implementers are responsible for a few unique items like the name.
-
-One particularly important item is the ``type`` property. This should be the
-class that is the scalar type for your data. For example, if you were writing an
-extension array for IP Address data, this might be ``ipaddress.IPv4Address``.
-
-See the `extension dtype source`_ for interface definition.
-
-:class:`pandas.api.extensions.ExtensionDtype` can be registered to pandas to allow creation via a string dtype name.
-This allows one to instantiate ``Series`` and ``.astype()`` with a registered string name, for
-example ``'category'`` is a registered string accessor for the ``CategoricalDtype``.
-
-See the `extension dtype dtypes`_ for more on how to register dtypes.
-
-:class:`~pandas.api.extensions.ExtensionArray`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This class provides all the array-like functionality. ExtensionArrays are
-limited to 1 dimension. An ExtensionArray is linked to an ExtensionDtype via the
-``dtype`` attribute.
-
-pandas makes no restrictions on how an extension array is created via its
-``__new__`` or ``__init__``, and puts no restrictions on how you store your
-data. We do require that your array be convertible to a NumPy array, even if
-this is relatively expensive (as it is for ``Categorical``).
-
-They may be backed by none, one, or many NumPy arrays. For example,
-:class:`pandas.Categorical` is an extension array backed by two arrays,
-one for codes and one for categories. An array of IPv6 addresses may
-be backed by a NumPy structured array with two fields, one for the
-lower 64 bits and one for the upper 64 bits. Or they may be backed
-by some other storage type, like Python lists.
-
-See the `extension array source`_ for the interface definition. The docstrings
-and comments contain guidance for properly implementing the interface.
-
-.. _extending.extension.operator:
-
-:class:`~pandas.api.extensions.ExtensionArray` operator support
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, there are no operators defined for the class :class:`~pandas.api.extensions.ExtensionArray`.
-There are two approaches for providing operator support for your ExtensionArray:
-
-1. Define each of the operators on your ``ExtensionArray`` subclass.
-2. Use an operator implementation from pandas that depends on operators that are already defined
- on the underlying elements (scalars) of the ExtensionArray.
-
-.. note::
-
- Regardless of the approach, you may want to set ``__array_priority__``
- if you want your implementation to be called when involved in binary operations
- with NumPy arrays.
-
-For the first approach, you define selected operators, e.g., ``__add__``, ``__le__``, etc. that
-you want your ``ExtensionArray`` subclass to support.
-
-The second approach assumes that the underlying elements (i.e., scalar type) of the ``ExtensionArray``
-have the individual operators already defined. In other words, if your ``ExtensionArray``
-named ``MyExtensionArray`` is implemented so that each element is an instance
-of the class ``MyExtensionElement``, then if the operators are defined
-for ``MyExtensionElement``, the second approach will automatically
-define the operators for ``MyExtensionArray``.
-
-A mixin class, :class:`~pandas.api.extensions.ExtensionScalarOpsMixin` supports this second
-approach. If developing an ``ExtensionArray`` subclass, for example ``MyExtensionArray``,
-can simply include ``ExtensionScalarOpsMixin`` as a parent class of ``MyExtensionArray``,
-and then call the methods :meth:`~MyExtensionArray._add_arithmetic_ops` and/or
-:meth:`~MyExtensionArray._add_comparison_ops` to hook the operators into
-your ``MyExtensionArray`` class, as follows:
-
-.. code-block:: python
-
- from pandas.api.extensions import ExtensionArray, ExtensionScalarOpsMixin
-
-
- class MyExtensionArray(ExtensionArray, ExtensionScalarOpsMixin):
- pass
-
-
- MyExtensionArray._add_arithmetic_ops()
- MyExtensionArray._add_comparison_ops()
-
-
-.. note::
-
- Since ``pandas`` automatically calls the underlying operator on each
- element one-by-one, this might not be as performant as implementing your own
- version of the associated operators directly on the ``ExtensionArray``.
-
-For arithmetic operations, this implementation will try to reconstruct a new
-``ExtensionArray`` with the result of the element-wise operation. Whether
-or not that succeeds depends on whether the operation returns a result
-that's valid for the ``ExtensionArray``. If an ``ExtensionArray`` cannot
-be reconstructed, an ndarray containing the scalars returned instead.
-
-For ease of implementation and consistency with operations between pandas
-and NumPy ndarrays, we recommend *not* handling Series and Indexes in your binary ops.
-Instead, you should detect these cases and return ``NotImplemented``.
-When pandas encounters an operation like ``op(Series, ExtensionArray)``, pandas
-will
-
-1. unbox the array from the ``Series`` (``Series.array``)
-2. call ``result = op(values, ExtensionArray)``
-3. re-box the result in a ``Series``
-
-.. _extending.extension.ufunc:
-
-NumPy universal functions
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:class:`Series` implements ``__array_ufunc__``. As part of the implementation,
-pandas unboxes the ``ExtensionArray`` from the :class:`Series`, applies the ufunc,
-and re-boxes it if necessary.
-
-If applicable, we highly recommend that you implement ``__array_ufunc__`` in your
-extension array to avoid coercion to an ndarray. See
-`the NumPy documentation `__
-for an example.
-
-As part of your implementation, we require that you defer to pandas when a pandas
-container (:class:`Series`, :class:`DataFrame`, :class:`Index`) is detected in ``inputs``.
-If any of those is present, you should return ``NotImplemented``. pandas will take care of
-unboxing the array from the container and re-calling the ufunc with the unwrapped input.
-
-.. _extending.extension.testing:
-
-Testing extension arrays
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-We provide a test suite for ensuring that your extension arrays satisfy the expected
-behavior. To use the test suite, you must provide several pytest fixtures and inherit
-from the base test class. The required fixtures are found in
-https://github.com/pandas-dev/pandas/blob/main/pandas/tests/extension/conftest.py.
-
-To use a test, subclass it:
-
-.. code-block:: python
-
- from pandas.tests.extension import base
-
-
- class TestConstructors(base.BaseConstructorsTests):
- pass
-
-
-See https://github.com/pandas-dev/pandas/blob/main/pandas/tests/extension/base/__init__.py
-for a list of all the tests available.
-
-.. _extending.extension.arrow:
-
-Compatibility with Apache Arrow
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-An ``ExtensionArray`` can support conversion to / from ``pyarrow`` arrays
-(and thus support for example serialization to the Parquet file format)
-by implementing two methods: ``ExtensionArray.__arrow_array__`` and
-``ExtensionDtype.__from_arrow__``.
-
-The ``ExtensionArray.__arrow_array__`` ensures that ``pyarrow`` knowns how
-to convert the specific extension array into a ``pyarrow.Array`` (also when
-included as a column in a pandas DataFrame):
-
-.. code-block:: python
-
- class MyExtensionArray(ExtensionArray):
- ...
-
- def __arrow_array__(self, type=None):
- # convert the underlying array values to a pyarrow Array
- import pyarrow
-
- return pyarrow.array(..., type=type)
-
-The ``ExtensionDtype.__from_arrow__`` method then controls the conversion
-back from pyarrow to a pandas ExtensionArray. This method receives a pyarrow
-``Array`` or ``ChunkedArray`` as only argument and is expected to return the
-appropriate pandas ``ExtensionArray`` for this dtype and the passed values:
-
-.. code-block:: none
-
- class ExtensionDtype:
- ...
-
- def __from_arrow__(self, array: pyarrow.Array/ChunkedArray) -> ExtensionArray:
- ...
-
-See more in the `Arrow documentation `__.
-
-Those methods have been implemented for the nullable integer and string extension
-dtypes included in pandas, and ensure roundtrip to pyarrow and the Parquet file format.
-
-.. _extension dtype dtypes: https://github.com/pandas-dev/pandas/blob/main/pandas/core/dtypes/dtypes.py
-.. _extension dtype source: https://github.com/pandas-dev/pandas/blob/main/pandas/core/dtypes/base.py
-.. _extension array source: https://github.com/pandas-dev/pandas/blob/main/pandas/core/arrays/base.py
-
-.. _extending.subclassing-pandas:
-
-Subclassing pandas data structures
-----------------------------------
-
-.. warning:: There are some easier alternatives before considering subclassing ``pandas`` data structures.
-
- 1. Extensible method chains with :ref:`pipe `
-
- 2. Use *composition*. See `here `_.
-
- 3. Extending by :ref:`registering an accessor `
-
- 4. Extending by :ref:`extension type `
-
-This section describes how to subclass ``pandas`` data structures to meet more specific needs. There are two points that need attention:
-
-1. Override constructor properties.
-2. Define original properties
-
-.. note::
-
- You can find a nice example in `geopandas `_ project.
-
-Override constructor properties
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Each data structure has several *constructor properties* for returning a new
-data structure as the result of an operation. By overriding these properties,
-you can retain subclasses through ``pandas`` data manipulations.
-
-There are 3 possible constructor properties to be defined on a subclass:
-
-* ``DataFrame/Series._constructor``: Used when a manipulation result has the same dimension as the original.
-* ``DataFrame._constructor_sliced``: Used when a ``DataFrame`` (sub-)class manipulation result should be a ``Series`` (sub-)class.
-* ``Series._constructor_expanddim``: Used when a ``Series`` (sub-)class manipulation result should be a ``DataFrame`` (sub-)class, e.g. ``Series.to_frame()``.
-
-Below example shows how to define ``SubclassedSeries`` and ``SubclassedDataFrame`` overriding constructor properties.
-
-.. code-block:: python
-
- class SubclassedSeries(pd.Series):
- @property
- def _constructor(self):
- return SubclassedSeries
-
- @property
- def _constructor_expanddim(self):
- return SubclassedDataFrame
-
-
- class SubclassedDataFrame(pd.DataFrame):
- @property
- def _constructor(self):
- return SubclassedDataFrame
-
- @property
- def _constructor_sliced(self):
- return SubclassedSeries
-
-.. code-block:: python
-
- >>> s = SubclassedSeries([1, 2, 3])
- >>> type(s)
-
-
- >>> to_framed = s.to_frame()
- >>> type(to_framed)
-
-
- >>> df = SubclassedDataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]})
- >>> df
- A B C
- 0 1 4 7
- 1 2 5 8
- 2 3 6 9
-
- >>> type(df)
-
-
- >>> sliced1 = df[["A", "B"]]
- >>> sliced1
- A B
- 0 1 4
- 1 2 5
- 2 3 6
-
- >>> type(sliced1)
-
-
- >>> sliced2 = df["A"]
- >>> sliced2
- 0 1
- 1 2
- 2 3
- Name: A, dtype: int64
-
- >>> type(sliced2)
-
-
-Define original properties
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To let original data structures have additional properties, you should let ``pandas`` know what properties are added. ``pandas`` maps unknown properties to data names overriding ``__getattribute__``. Defining original properties can be done in one of 2 ways:
-
-1. Define ``_internal_names`` and ``_internal_names_set`` for temporary properties which WILL NOT be passed to manipulation results.
-2. Define ``_metadata`` for normal properties which will be passed to manipulation results.
-
-Below is an example to define two original properties, "internal_cache" as a temporary property and "added_property" as a normal property
-
-.. code-block:: python
-
- class SubclassedDataFrame2(pd.DataFrame):
-
- # temporary properties
- _internal_names = pd.DataFrame._internal_names + ["internal_cache"]
- _internal_names_set = set(_internal_names)
-
- # normal properties
- _metadata = ["added_property"]
-
- @property
- def _constructor(self):
- return SubclassedDataFrame2
-
-.. code-block:: python
-
- >>> df = SubclassedDataFrame2({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]})
- >>> df
- A B C
- 0 1 4 7
- 1 2 5 8
- 2 3 6 9
-
- >>> df.internal_cache = "cached"
- >>> df.added_property = "property"
-
- >>> df.internal_cache
- cached
- >>> df.added_property
- property
-
- # properties defined in _internal_names is reset after manipulation
- >>> df[["A", "B"]].internal_cache
- AttributeError: 'SubclassedDataFrame2' object has no attribute 'internal_cache'
-
- # properties defined in _metadata are retained
- >>> df[["A", "B"]].added_property
- property
-
-.. _extending.plotting-backends:
-
-Plotting backends
------------------
-
-pandas can be extended with third-party plotting backends. The
-main idea is letting users select a plotting backend different than the provided
-one based on Matplotlib. For example:
-
-.. code-block:: python
-
- >>> pd.set_option("plotting.backend", "backend.module")
- >>> pd.Series([1, 2, 3]).plot()
-
-This would be more or less equivalent to:
-
-.. code-block:: python
-
- >>> import backend.module
- >>> backend.module.plot(pd.Series([1, 2, 3]))
-
-The backend module can then use other visualization tools (Bokeh, Altair,...)
-to generate the plots.
-
-Libraries implementing the plotting backend should use `entry points `__
-to make their backend discoverable to pandas. The key is ``"pandas_plotting_backends"``. For example, pandas
-registers the default "matplotlib" backend as follows.
-
-.. code-block:: python
-
- # in setup.py
- setup( # noqa: F821
- ...,
- entry_points={
- "pandas_plotting_backends": [
- "matplotlib = pandas:plotting._matplotlib",
- ],
- },
- )
-
-
-More information on how to implement a third-party plotting backend can be found at
-https://github.com/pandas-dev/pandas/blob/main/pandas/plotting/__init__.py#L1.
-
-.. _extending.pandas_priority:
-
-Arithmetic with 3rd party types
--------------------------------
-
-In order to control how arithmetic works between a custom type and a pandas type,
-implement ``__pandas_priority__``. Similar to numpy's ``__array_priority__``
-semantics, arithmetic methods on :class:`DataFrame`, :class:`Series`, and :class:`Index`
-objects will delegate to ``other``, if it has an attribute ``__pandas_priority__`` with a higher value.
-
-By default, pandas objects try to operate with other objects, even if they are not types known to pandas:
-
-.. code-block:: python
-
- >>> pd.Series([1, 2]) + [10, 20]
- 0 11
- 1 22
- dtype: int64
-
-In the example above, if ``[10, 20]`` was a custom type that can be understood as a list, pandas objects will still operate with it in the same way.
-
-In some cases, it is useful to delegate to the other type the operation. For example, consider I implement a
-custom list object, and I want the result of adding my custom list with a pandas :class:`Series` to be an instance of my list
-and not a :class:`Series` as seen in the previous example. This is now possible by defining the ``__pandas_priority__`` attribute
-of my custom list, and setting it to a higher value, than the priority of the pandas objects I want to operate with.
-
-The ``__pandas_priority__`` of :class:`DataFrame`, :class:`Series`, and :class:`Index` are ``4000``, ``3000``, and ``2000`` respectively. The base ``ExtensionArray.__pandas_priority__`` is ``1000``.
-
-.. code-block:: python
-
- class CustomList(list):
- __pandas_priority__ = 5000
-
- def __radd__(self, other):
- # return `self` and not the addition for simplicity
- return self
-
- custom = CustomList()
- series = pd.Series([1, 2, 3])
-
- # Series refuses to add custom, since it's an unknown type with higher priority
- assert series.__add__(custom) is NotImplemented
-
- # This will cause the custom class `__radd__` being used instead
- assert series + custom is custom
diff --git a/doc/source/development/gitpod-imgs/gitpod-dashboard-stop.png b/doc/source/development/gitpod-imgs/gitpod-dashboard-stop.png
deleted file mode 100644
index b64790a9866465830505ff0372c8318ff23148d6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 197766
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
z